Definition and Encoding

The message structure that is used in the zForce communication protocol is defined in the zForce PDU definition file. PDU stands for Protocol Data Unit, the specific block of information that is going to be transferred. The definition is written according to Abstract Syntax Notation One (ASN.1), a standardized way to describe data regardless of language implementation, hardware system and operation system (ISO/IEC 8824).

To get the message data format used for information transfer, a set of encoding rules are applied to the ASN.1 definitions. The zForce communication protocol uses the Distinguished Encoding Rules (DER) to serialize the information that is going to be transferred. For more information, refer to Understanding the zForce ASN1 Protocol.

ASN.1 defines a number of universal types, from which all other types inherit traits. The result is that a set of encoding rules that covers the universal types can serialize any PDU, as long as the identifier numbers and the definition categories are available. The identifier numbers and definition categories for the zForce PDU are included in the PDU definition file.  

Downloading the definition file

Download the zForce® PDU definition files from Downloads.

The zForce message

The communication protocol uses three types of messages:

• Requests
• Responses
• Notifications

The host sends a request to the sensor module, and the device responds with a response. The device may send notifications to the host at any time.

All messages contain a virtual device address. Virtual devices are functionally isolated from each other, and communicate separately with the host. There are two types of virtual devices:

• Platform – represents the system.
• Air – represents one Neonode Touch Sensor Module.

A sensor module will always contain one platform virtual device and can contain any number of instances of other virtual device types.

In the definition file, all sensor messages are described as instances of the top level PDU ProtocolMessage which have three child PDUs:

PDU Description in GSER Notation

The PDU specifies the following message specification templates, notifications and pairs of requests and responses:

The messages described here are encoded using the man-readable Generic String Encoding Rules (GSER), as the messages encoded according to DER can be difficult to read for a human.

A short introduction to the GSER notation:

• Sequences and/or sets (items containing sub items) are shown as curly brackets: { <sub elements> }
• Values encoded as octet strings are written as hexadecimal octets enclosed within single quotes and suffixed with H: 'FF9900'H
• Bit strings are also shown as octet strings when the number of bits is a multiple of 8, otherwise each bit is shown as a single 1 or 0, and suffixed with B: '11010101001'B
• In a choice element, the selected type is denoted by its name followed by a colon: request:

Refer to Generic String Encoding Rules (GSER) for ASN.1 Types for a full reference.

The tool FFASN1Dump can transcode from GSER to DER:

ffasn1dump -I gser -O der zforce_pdu_def.asn ProtocolMessage <input file> <output file>

Application Interface

The application interface specifies what requests can be made and what responses and notifications they activate. Messages are specified according to the following templates:

request: {
  deviceAddress <address>,
  <request command>
}

response: {
  deviceAddress <address>,
  <command response>
}

notification: {
  deviceAddress <address>,
  <notification>
  notificationTimestamp <timestamp>
}

Where

• Address is an octet string with 2 octets, device type and index:
  '<device type><index>'H. The available device types are:

  Device type	Device
  0	Platform
  1	Core
  2	Air
  3	Plus
  4	Lightning

  Example: ‘0000’H for platform (there can be only one platform device per sensor system).
  
  

• Timestamp is a 32 bit signed integer that has variable length between 1-4 byte (dynamic) representing values between 0-2^31-1 at 32 KHz +/- 5%.

Commands:

Protocol version 1.12

Protocol version 1.11

Protocol version 1.10

Protocol version 1.9

Protocol version 1.8

Protocol version 1.7