Custom Payloads

Starting Ubiqua version 2.3 users can create custom decoders for the MAC payload, RF4CE, and Application Zigbee layers. The custom decoding is described by the user in an XML file.

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

Create the custom payload XML file. The XML file must be named APS-Custom.xml, RF4CE-Custom.xml or MAC-Custom-Payload.xml depending on which will be used.
With Ubiqua closed, add the custom xml file in the Ubiqua Data Folder. Depending on your operating system the Ubiqua Data Folder can be located at,

-Windows 8.1 or later (Subscription Licenses) : %AppData%\Ubilogix\Ubiqua.
Run Ubiqua and enable the custom decoding, you can access this option through the Tools option in the main menu, then choose Preferences, and the General tab will open, scroll down to the User Options, there you can find three options, for the custom decoding of APS, MAC, and RF4CE payloads.

Create the Custom Decoder

The custom decoders are constructed by following the XML schema Decoders.xsd. The following 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. This element includes important xml attributes used to identify and assign meta information to the field. Some of the most important attributes of the Field element are:

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 value of 16 bits length and 8 bits offset, will be labeled in the Packet View as Command Type and can be referenced in other fields of the decoders with the Name CommandType.

The Binding element

The Binding element creates a link with a variable or field. The length of the Field element will be determined depending on the value of the linked element used as Source for the binding.

Note: A variable can be defined with the Name attribute in a Field element or as a Variable element at the beginning of the decoder.

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 used to indicate how to parse and display the field value. The possible data types for this element are:

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 IsRepeatable attribute of the Field element allows creating a loop functionality. If it is set to true, the definition of the field will be repeated until the length is equal 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 MAC payload example

The MAC Custom Payload only works using the IEEE 802.15.4-2003, IEEE 802.15.4-2006 and IEEE 802.15.4-2015 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-Payload.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 NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF UBILOGIX HAS
    BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    Copyright (C) 2020 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 RF4CE payload example

The RF4CE Custom Payload only works using the Zigbee RF4CE protocol stack. RF4CE-Custom.xml contains the MAC header variables needed to decode the custom payload.

<?xml version="1.0" encoding="utf-8" ?>
<!--
    File: RF4CE-Custom.xml
    Abstract: The layer definition of RF4CE-NWK 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 NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF UBILOGIX HAS
    BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    Copyright (C) 2020 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="RF4CE 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>
    <!--RF4CE Header Variables-->
    <Variable Name="RF4CEFrameType"         Value="0xF" />
    <Variable Name="SecurityEnabled"        Value="0xF" />
    <Variable Name="RF4CEProtocolVersion"   Value="0xF" />
    <Variable Name="RF4CEChannelDesignator" Value="0xF" />
    <Variable Name="FrameCounter"           Value="0xFFFFFFFF" />
    <Variable Name="ProfileId"              Value="0xFF" />
    <Variable Name="RF4CEVendorId"          Value="0xFFFF" />
 </Variables>


  <Fields>

    <!--For RF4CE Vendor Specific Payload-->
    <Field Name="DataPayload" Label="DataPayload">
      <Field Label="Vendor Specific Payload">
        <!--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 NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF UBILOGIX HAS 
    BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

    Copyright (C) 2019 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="OrangeField" Value="Orange" />
    <Color Name="YellowField" Value="Yellow" />
    <Color Name="LightBlueField" Value="LightBlue" />
    <Color Name="BlackField" Value="Black" />
    <Color Name="RedField" Value="Red" />
    <Color Name="PinkField" Value="Pink" />
    <Color Name="PurpleField" Value="Purple" />
    <Color Name="DarkGreenField" Value="DarkGreen" />
    <Color Name="DarkBlueField" Value="DarkBlue" />
    <Color Name="BrownField" Value="Brown" />
    <Color Name="GrayField" Value="Gray" />
    <Color Name="LightGreenField" 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="ZclMnfctrCommand" Value="0xFF" />
    <!--ZCL Specific to Cluster Command from ZCL Header-->
    <Variable Name="ZclSpecificCommand" Value="0xFF" />
    <!--Transaction Sequence Number value from ZCL Header-->
    <Variable Name="ZclTransSequenceNumber" Value="0xFF" />
 </Variables>


  <Fields>

    <!--For APS Custom Payload for Manufacturer Specific Profile-->
    <Field Name="MnfctrProfileAPSPayload" Label="Manufacturer Specific Profile Payload">
      <Field Label="Custom Manuf. Specific Profile Payload" Length="Stretch" NodeColor="PurpleField">
        <!--Payload Here-->
      </Field>
    </Field>

    <!--For APS Custom Payload for Public Profile and Manufacturer Specific Cluster-->
    <Field Name="PublicProfileMnfctrClusterAPSPayload" Label="Example Manufacturer Specific Cluster APS Payload">
      <Field Label="Custom Manuf. Specific Cluster APS Payload" Length="Stretch" NodeColor="LightGreenField">
        <!--Payload Here-->
      </Field>
    </Field>

    <!--For ZCL Custom Payload for Manufacturer Specific Command-->
    <Field Name="ZclMnfctrSpecCommand" Label="Manufacturer Specific Command">
      <!--Payload  Here-->
      <Field Label="Custom ZCL Manuf. Specific Command Payload" GroupsSource="ZclMnfctrCommand" >
        <DefaultFieldsGroup>
          <Field Label="Example Field"/>
        </DefaultFieldsGroup>
      </Field>
    </Field>
  </Fields>
</Layer>

Manufacturer Specific Profile APS Payload

Notice the difference in the Layer name and Payload field label when APS Custom decoder is enabled, and the APSCustom.xml example file above is used.

Manuf. Specific Profile APS Payload

ZCL Header for Zigbee APS Private Clusters

For a private cluster in a public profile, Ubiqua will try to decode the first APS payload bytes as the ZCL header. If you do not wish to have these bytes decoded as the ZCL header and would like to have your own decoder, then you need to enable the APS Custom Payload. Notice the difference in the layer name and how the ZCL header decoder is removed to allow the user to decide what will be the payload. If you wish to have the ZCL Header and decode your command, contact us at support@ubilogix.com.

Private Cluster Payload with ZCL Header

Custom Private Cluster APS Payload

ZCL Manufacturer Specific Command

Notice the difference in the Layer name and Payload field label when APS Custom decoder is enabled, and the APSCustom.xml example file above is used.

ZCL Manufacturer Specific Command

Custom ZCL Manufacturer Specific Command