Custom Payloads

Starting Ubiqua version 1.4, users are now able to use custom decoders for the Mac payload and Application Zigbee layers. The custom decoding is described by the user in a XML file.

To integrate the custom payload and start enjoying this functionality follow these instructions:

  1. Create the custom payload XML file. The XML file has to be named with a specific name as it is required for the proper functionality with Ubiqua; the file depending of the case may be named as APS-Custom.xml or MAC-Custom-Payload.xml.

  2. With Ubiqua closed, add the APS-Custom.xml file and/or MAC-Custom-Payload.xml file in the Ubiqua Data Folder. Depending of your operating system the Ubiqua Data Folder can be located at,

    • Windows XP: C:\Documents and Settings\All Users\Application Data\Ubilogix\Ubiqua.
    • Windows Vista or later: C:\ProgramData\Ubilogix\Ubiqua.
  3. Run Ubiqua and enable the custom decoding, you can access this option through the Tools option of the main menu, then choose Options, and the General tab will open, at the bottom of this window you can find both options, custom decoding of APS or MAC payloads.

Creation of the custom decoder

The custom decoders are constructed by following the XML schema Decoders.xsd. Next section briefly explains the different elements and attributes used by the XML custom decoder.

The "Field" element

The "Field" element, reads an amount of bits from the frame. The Field element includes important xml attributes used for identifying and assigning meta information to the field. Some of the important attributes of the Field element are the following:

  • Name – It's an optional attribute that assigns an ID to the value that was read into the Field element.

  • IsGroup – Hides a Field element from the Packet View.

  • Label – This attribute assigns a label to display into the PacketView, if the Label is not present, the default Label is "reserved".

  • Offset – It's an Attribute with an integer value that defines the amount of offset bits from where the reading begins.

  • Type – Defines the data type that will be interpreted on the PacketView.

An example of Field:

<Field Name="CommandType" Label="Command Type" Offset="8" Length="16" Type="Integer" />

In the example above, the field Contains an ID "CommandType" with the value that was read, has an offset of 8 bits, a length of 16 bits and the data type is integer. The label displayed into the PacketView is "Command Type".

The "Binding" element

The "binding" element creates a link with a variable. Depending of the value of the element, the length of the field element will be determined.

Note: A variable is defined with the "name" attribute in the Field element.

Example:

<Field Label="Command Type" Name="CommandType" Length="8">
      <Options>
        <Option Value="0x00" Label="Start" />
        <Option Value="0x01" Label="Stop" />
        <Option Value="0x02" Label="Pause" />
        <Option Value="0x03" Label="Configure"/>
      </Options>
</Field>
 <!-- If the "CommandType" is 0x00 then the length of  "Command Payload" field is 8 bits (0x01 -> 16,  0x02-> 24, 0x03 -> 32, any other value is 0 bits)  -->
    <Field Label="Command Payload">
      <Field.Length>
        <Binding Source="CommandType">
          <Case Value="0x00" Result="8" />
          <Case Value="0x01" Result="16" />
          <Case Value="0x02" Result="24" />
          <Case Value="0x03" Result="32" />
          <Case Value="0x04-0xFF" Result="0" />
        </Binding>
      </Field.Length>
      <!--Payload-->
    </Field>

Custom decoder Field data Types

Each Field element has a Type attribute which is used to indicate how to parse and display the field value. The possible data types of the Type attribute are the following:

  • Hexadecimal – Value should be parsed as an unsigned integer and displayed as an hexadecimal string (default).

  • Bits – Value should be parsed as an unsigned integer and displayed as an element of a bitmap.

  • Integer – Value should be parsed and displayed as an unsigned integer.

  • SignedInteger – Value should be parsed and displayed as a signed integer.

  • String – Value should be parsed and displayed as an ASCII string.

  • Boolean – Value should be parsed and displayed as a boolean.

  • DateTime – Value should be parsed and displayed as a date time. The format must be "yyyy-MM-dd HH:mm:ss.SSSSSS", as defined by the LDML standard.

  • Time - Value should be parsed and displayed as a time. The format must be "HH:mm:ss.SSSSSS", as defined by the LDML standard.

  • Seconds – Value should be parsed and displayed as seconds. The format must be "ss.SSSSSS", as defined by the LDML standard.

  • SignalPower – Value should be parsed as an integer and displayed with the "dBm" postfix.

  • Address – Value should be parsed as an unsigned integer and displayed as an hexadecimal string with digits separated by a colon only if the length is 6 or 8 bytes.

  • Key – Value should be parsed as an hexadecimal string and displayed as a security key.

Loop functionality

The "isRepeteable" attribute of the Field element allows creating a Field with a loop functionality. If the "isRepeteable" is sets to true, the field repeats the content until the length is equals to 0.

Example:

 <Field Label="Commands" Length="80">
      <Field Label="Command" Length="8" IsRepeatable="true">
        <Field Label="Field 1" Length="2" />
        <Field Label="Field 2" Length="6" />
      </Field>
 </Field>

In the above example, the field with the label "Command" will be repeated 10 times because its length is 8 bytes and the length of the Commands field is 80 bytes.

Hiding unnecessary fields in the Ubiqua Packet View.

If there is a "Field" element that is not required to be visible in the Packet View, add the "isGroup" attribute.

Example:

<Field Label="Values" IsGroup="true">
 <Field Label="Value" Length="8" />
</Field>

In the above example only the Field with the label "Value" is shown in the Packet View.

Examples

##Custom decoder complete examples

Custom MAC payload example

The MAC Custom Payload only works using the IEEE 802.15.4-2003 and IEEE 802.15.4-2006 protocol stacks. MAC-Custom-Payload.xml contains the MAC header variables needed to decode the custom payload.


<?xml version="1.0" encoding="UTF-8"?>
<!-- 
    File: MAC-Custom.xml 
    Abstract: The layer definition of MAC Custom Payload 

    Disclaimer: IMPORTANT: This Ubilogix software is supplied to you by Ubilogix 
    International Inc. ("Ubilogix") in consideration of your agreement to the 
    following terms, and your use or modification of this Ubilogix software 
    constitutes acceptance of these terms. If you do not agree to these terms, 
    please do not use or modify this Ubilogix software. 

    In consideration of your agreement to abide by the following terms, and subject 
    to these terms, Ubilogix grants you a personal, non-exclusive license, under 
    Ubilogix's copyrights in this original Ubilogix software ("the Ubilogix 
    Software"), to use and modify the Ubilogix Software provided that you must 
    retain this notice and the following text and disclaimers. Except as expressly 
    stated in this notice, no other rights or licenses, express or implied, are 
    granted by Ubilogix herein, including but not limited to any patent rights that 
    my be infringed by your derivative works or by other works in which the Ubilogix 
    Software may be incorporated. 

    THE UBILOGIX SOFTWARE IS PROVIDED BY UBILOGIX ON AS "AS IS" BASIS. UBILOGIX 
    MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE 
    IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A 
    PARTICULAR PURPOSE, REGARDING THE UBILOGIX SOFTWARE OR ITS USE AND OPERATION 
    ALONE OR IN COMBINATION WITH YOUR PRODUCTS. 

    IN NO EVENT SHALL UBILOGIX BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR 
    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 
    GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
    ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION 
    OF THE UBILOGIX SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, 
    TORT (INCLUDING NEGLICENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF UBILOGIX HAS 
    BEEN ADVICED OF THE POSSIBLITY OF SUCH DAMAGE. 

    Copyright (C) 2015 Ubilogix International, Inc. All rights reserved. 

-->
<Layer xmlns="urn:ubilogix:decoders"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:ubilogix:decoders ../../Schemas/Decoders.xsd"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    Name="MAC Custom Payload" ShortName="Custom" Language="en-US" Version="1.0.1">

  <Colors>
    <Color Name="NC001" Value="Black" />
    <Color Name="NC002" Value="Red" />
    <Color Name="RC001" Value="Pink" />
    <Color Name="RC002" Value="LightGreen" />
  </Colors>
  <Variables>
    <!--The Frame Type from MAC header-->
    <Variable Name="FrameType" Value="0xF" />
    <!--MAC security bit from MAC header -->
    <Variable Name="MacSecurityEnabled" Value="0xF" />
    <!--The destination PAN ID-->
    <Variable Name="DstPanId" Value="0xF" />
    <!--The destination Address-->
    <Variable Name="DstAddr" Value="0xF" />
    <!--The Source PAN ID-->
    <Variable Name="SrcPanId" Value="0xF" />
    <!--The Source Address-->
    <Variable Name="SrcAddr" Value="0xF" />
  </Variables>

  <Fields>
    <Field Name="DataPayload" Label="Data Payload">
      <Field Label="Payload" Length="Stretch">
        <!--Payload Here-->
      </Field>
    </Field>
  </Fields>
</Layer>

Custom APS decoder example

The APS Custom Layer allows decoding the payload for APS when the Profile ID is private or to decode a specific command from ZCL when the Cluster ID is private.

<?xml version="1.0" encoding="utf-8" ?>
<!-- 
    File: APS-Custom.xml 
    Abstract: The layer definition of APS Custom Payload 

    Disclaimer: IMPORTANT: This Ubilogix software is supplied to you by Ubilogix 
    International Inc. ("Ubilogix") in consideration of your agreement to the 
    following terms, and your use or modification of this Ubilogix software 
    constitutes acceptance of these terms. If you do not agree to these terms, 
    please do not use or modify this Ubilogix software. 

    In consideration of your agreement to abide by the following terms, and subject 
    to these terms, Ubilogix grants you a personal, non-exclusive license, under 
    Ubilogix's copyrights in this original Ubilogix software ("the Ubilogix 
    Software"), to use and modify the Ubilogix Software provided that you must 
    retain this notice and the following text and disclaimers. Except as expressly 
    stated in this notice, no other rights or licenses, express or implied, are 
    granted by Ubilogix herein, including but not limited to any patent rights that 
    my be infringed by your derivative works or by other works in which the Ubilogix 
    Software may be incorporated. 

    THE UBILOGIX SOFTWARE IS PROVIDED BY UBILOGIX ON AS "AS IS" BASIS. UBILOGIX 
    MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE 
    IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A 
    PARTICULAR PURPOSE, REGARDING THE UBILOGIX SOFTWARE OR ITS USE AND OPERATION 
    ALONE OR IN COMBINATION WITH YOUR PRODUCTS. 

    IN NO EVENT SHALL UBILOGIX BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR 
    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 
    GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
    ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION 
    OF THE UBILOGIX SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, 
    TORT (INCLUDING NEGLICENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF UBILOGIX HAS 
    BEEN ADVICED OF THE POSSIBLITY OF SUCH DAMAGE. 

    Copyright (C) 2015 Ubilogix International, Inc. All rights reserved. 

-->
<Layer xmlns="urn:ubilogix:decoders"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:ubilogix:decoders ../../Schemas/Decoders.xsd"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    Name="APS Custom" ShortName="Custom" Language="en-US" Version="1.0.1">

  <Colors>
    <Color Name="NC001" Value="Black" />
    <Color Name="NC002" Value="Red" />
    <Color Name="RC001" Value="Pink" />
    <Color Name="RC002" Value="LightGreen" />
  </Colors>
  <Variables>
    <!--APS Header Variables-->
    <Variable Name="ApsZclClusterId" Value="0xFFFF" />
    <!--Cluster ID value from APS Header-->
    <Variable Name="ApsFrameType" Value="0xF" />
    <!--Frame Type value from APS Header-->
    <Variable Name="DeliveryMode" Value="0xF" />
    <!--Delivery Mode value from APS Header-->
    <Variable Name="AckFormat" Value="0xF" />
    <!--Acknowledgement Format value from APS Header-->
    <Variable Name="SecurityEnabled" Value="0xF" />
    <!--Security Enabled value from APS Header-->
    <Variable Name="DstEndpoint" Value="0xFF" />
    <!--Destination Endpoint value from APS Header-->
    <Variable Name="ProfileId" Value="0xFF" />
    <!--Profile ID value from APS Header-->
    <!--ZCL Header Variables-->
    <Variable Name="ZclGeneralCmdFrame" Value="0xFFF" />
    <!--General Command Frame value from ZCL Header-->
    <Variable Name="ZclDirection" Value="0xF" />
    <!--Direction value from ZCL Header-->
    <Variable Name="ZclFrameType" Value="0xF" />
    <!--Frame Type value from ZCL Header-->
    <Variable Name="ManufacturerSpecific" Value="0xF" />
    <!--Manufacturer Specific value from ZCL Header-->
    <Variable Name="ZclSpecificPrivatedCmd" Value="0xFF" />
    <!--Specific Privated Command value from ZCL Header-->
    <Variable Name="ZclTransSequenceNumber" Value="0xFF" />
    <!--Transaction Sequence Number value from ZCL Header-->
    <Variable Name="ZclSpecificCommand" Value="0xFF" />
  </Variables>


  <Fields>

    <!--For APS Custom Payload-->
    <Field Name="DataPayload" Label="DataPayload">
      <Field Label="APS Payload">
        <!--Payload Here-->
      </Field>
    </Field>

    <!--For ZCL Custom Specific Command-->
    <Field Name="SpecificCommandPayload" Label="SpecificCommandPayload">
      <Field Label="Specific Command Payload" Length="Stretch">
        <!--Payload  Here-->
      </Field>
    </Field>

    <!--For ZCL Custom Frame Type-->
    <Field Name="ZclCustomFrameType" Label="ZclCustomFrameType">
      <Field Label="Private Payload" Length="Stretch">
        <!--Payload  Here-->
      </Field>
    </Field>
  </Fields>
</Layer>

Specific functionality examples

The following examples shows some of the functionality used for defining your own custom decoder.

Example 1

In this example, depending of the value of the "Command Type" Field the payload will be decoded accordingly. The example uses a Field named "Payload Field", with this field the length of the payload is calculated.

    <Field Label="Custom Payload Enabled" Length="Stretch">
        <!--Reads a field with 8 bits of length , saves the value of the field in "CommandType" and display the "Type" of command depending of the value-->
        <Field Name="CommandType" Label="Command Type" Length="8">
          <Options DefaultLabel="Unknown Command">
            <Option Value="0x00" Label="Type 1"/>
            <Option Value="0x01" Label="Type 2"/>
            <Option Value="0x02" Label="Type 3"/>
            <Option Value="0x03" Label="Type 4"/>
          </Options>
        </Field>
        <!--Reads a field with 16 bits of length, saves the value in "PayloadLength"-->
        <Field Name="PayloadLength" Label="Payload Length" Length="16" Type="Integer">
          <Options DefaultLabel="Bits" />
        </Field>
        <!--Depending the value of "CommandType" appears the Command Type N-->
        <Field Label="Payload" GroupsSource="CommandType">
          <DefaultFieldsGroup>
            <Field Label="Unknown Command Payload" Length="Stretch" />
          </DefaultFieldsGroup>
          <!-- If the Command Type is 0x00-->
          <FieldsGroup Group="0x00" Label="Payload Command Type 1">
            <Field Label="Payload Command Type 1" NodeColor="NC001">
              <Field.Length>
                <!-- The length of this field is based on the value of the field PayloadLength -->
                <Binding Source="PayloadLength" DefaultResultMultiplier="1" />
              </Field.Length>
              <Field Label="Payload 1" Length="Auto">
                <Field Label="Number of Company" Length="8" Type="Integer" />
                <Field Label="Name of Company" Length="80" Type="String" />
                <Field Name="Status" Label="Status" Length="8">
                  <Options>
                    <Option Value="0x00-0xF0" Label="OK" />
                    <Option Value="0xF1-0xFF" Label="Bad"/>
                  </Options>
                </Field>

                <!-- Field "Condition" appear if Status is 0x00 to 0xF0-->
                <Field Label="Condition">
                  <Field.Length>
                    <Binding Source="Status">
                      <Case Value="0x00-0xF0" Result="Auto"/>
                    </Binding>
                  </Field.Length>
                  <Field Label="Payload" Length="Stretch" />
                </Field>

              </Field>
            </Field>
          </FieldsGroup>

          <!-- If the Command Type is 0x01-->
          <FieldsGroup Group="0x01" Label="Payload Command Type 2">
            <Field Label="Payload Command Type 2" NodeColor="NC001">
              <Field.Length>
                <!-- The length of this field is based on the value of the field PayloadLength -->
                <Binding Source="PayloadLength" DefaultResultMultiplier="1" />
              </Field.Length>
              <Field Label="Payload 2" Length="Stretch" />
            </Field>
          </FieldsGroup>

          <!-- If the Command Type is 0x02-->
          <FieldsGroup Group="0x02" Label="Payload Command Type 3">
            <Field Label="Payload Command Type 1" NodeColor="NC002">
              <Field.Length>
                <!-- The length of this field is based on the value of the field PayloadLength -->
                <Binding Source="PayloadLength" DefaultResultMultiplier="1" />
              </Field.Length>
              <Field Label="Payload 2" Length="Stretch" />
            </Field>
          </FieldsGroup>

          <!-- If the Command Type is 0x03-->
          <FieldsGroup Group="0x03" Label="Payload Command Type 4">
            <Field Label="Payload Command Type 1" NodeColor="NC002">
              <Field.Length>
                <!-- The length of this field is based on the value of the field PayloadLength -->
                <Binding Source="PayloadLength" DefaultResultMultiplier="1" />
              </Field.Length>
              <Field Label="Payload 2" Length="Stretch" />
            </Field>
          </FieldsGroup>
        </Field>
      </Field>

Example 2

This example illustrates the use of the ZCL Header.

<Field Label="Payload Example 2" Length="Stretch">

        <!--To include the ZCL Header decoding, is needed add the next line, if the APS Payload custom 
        do not include decoding for ZCL Header just omits the next line-->
        <Field Label="ZCL Header">
          <Break Target="Layer" LayerName="Zigbee ZCL" FieldName="DataPayload" />
        </Field>

        <Field Label="Command Type" IsGroup="true" GroupsSource="ZclFrameType">
          <FieldsGroup Group="0x1" Label="Specific Command">
            <Field Label="Specific Command Payload" GroupsSource="ZclSpecificPrivatedCmd">
              <FieldsGroup Group="0x00" Label="Command Type 0">
                <Field Label="Command Type 0" Length="Stretch" />
              </FieldsGroup>
              <FieldsGroup Group="0x01" Label="Command Type 1">
                <Field Label="Command Type 1" Length="Stretch" />
              </FieldsGroup>
              <!--More FieldsGroup with different "Group" value-->
            </Field>              
          </FieldsGroup>
        </Field>
      </Field>