Understanding the zForce ASN.1 Serialization Protocol

All communication with the zForce AIR Touch sensor is serialized with our ASN.1 serialization protocol, and when implementing your own solution for the touch sensor it is vital to know how to encode and decode it. This article will go through some basics of ASN.1 and then the encoding of a DeviceConfiguration Message.

Type, Length, Value

All ASN.1 messages are structured by type, length and value:

• Type describes the type of the whole message or a subpart of a message. Type includes information on class and tag number.
• Length defines how many bytes there are in the message or in a subpart of the message.
• Value is the actual value you are sending to the device, it is either a primitive value or a list. The primitive value types that are used in this protocol are:
  • Integer
  • Boolean
  • Octet String
  • Bit String

The Type Byte(s)
Type bytes can be constructed or primitive. A constructed type is a list, and in this protocol, all lists are defined by a sequence, and will hereafter be referred to as sequences.
Class tags and tag numbers are used to encode a type byte. The following ASN.1 class tags are used:

The encoding for tag numbers up to and including 30:

In short this means that the 8th and 7th bits are reserved to specify the class, and the 6th bit is reserved to show if it is a sequence or if it is a primitive type. Bits 5 - 1 are used to specify the tag number.
The command DeviceConfiguration as seen in the protocol
deviceConfiguration [APPLICATION 19] Sequence
For example, DeviceConfiguration has 19 as tag number, and the type byte for deviceConfiguration looks like this when it is represented as an octet:

All of the hexadecimal numbers are then added together → 0x40 + 0x20 + 0x10 + 0x02 + 0x01 = 0x73.

The Length Byte(s)

The length byte defines the number of bytes in the Value byte(s) that follows it, and if the length of the Value is 127 or below the length byte is only one byte.
If the length of the whole value is for example, 0x32, the length byte will look like this:

If the number of value bytes is higher than 127, the length byte splits into several bytes according to the following description:.
Example: The following octet indicates that there are 2 length bytes to read in addition to the first one specified below. The sum of the two following length bytes is the length of the value.

The Value Byte(s)

The value byte(s) can be as few as one byte or they can be a whole sequence following the Type Length Value format.

Primitive Values

• Integers are signed and are represented by one or more bytes. An integer between 0 and 127 is represented by one byte (00 to 7F). An integer between 128 and 32767 is represented by two bytes (00 80 to 7F FF).
• A Boolean only requires one byte, since it is either true or false. The Boolean is either 0x00 or 0xFF.
• Octet String takes up just as many bytes as the number of octets.
• The number of bytes needed to represent a bit string depends on the number of bits and is easily explained in code:

int valueLength = 0;
 
void CalculateValueLength()
{
        valueLength = bitString.Length / 8;
 
        if((bitString.Length % 8) != 0)
        {
               valueLength++;
        }
}

Request, Response, and Notification

When the host is communicating with the sensor, all of the messages are defined as either request, response, or notification.

• Request is a message that is sent to the sensor from the host.
• Response is a message that responds to the request.
• Notification is a message that is read by the hostand is generated without any input from the host, for example a touch message or a boot complete message.

The messages look like this in the protocol:
Message Definition
    ProtocolMessage ::= CHOICE {
        request [PRIVATE 14] Message,
        response [PRIVATE 15] Message,
        notification [PRIVATE 16] Notification
    }
All three have the class tag private, and they are all sequences which means that the 8th, 7th, and 6th bits are all set. In binary this evaluates to 1110 0000 which in hexadecimal translates to 0xE0.
Now all that needs to be done is to define which type of message it is, which in this case is either tag number 14, 15, or 16. In order to define a request, tag number 14 (0x0E) needs to be added to 0xE0, which sums up to 0xEE.

Device Address

All messages include a Device Address. Most messages go to the Air Device, but some go to the Platform Device.
In the protocol, the DeviceAddress looks like this:
Device Address Definition
    DeviceAddress ::= [APPLICATION 0] OCTET STRING (SIZE (2))
    – Addressing information used when multiple touch devices are present
    – in the system.
    – Byte0 - deviceType, Byte1 - deviceIndex
    – DeviceTypes:    0x00    -    Platform
    --                0x01    -    zForce Core
    --                0x02    -    zForce Air
    --                0x03    -    zForce Plus
    --                0x04    -    Lighting devices

1. DeviceAddress has the class bits set to Application, and contains two octet strings. An octet string is primitive, and therefore the 6th bit is set to 0. In binary this evaluates to 0100 0000 and in hexadecimal that is 0x40.
2. Add the device type which in this case is the zForce Air, and is represented by 0x02.
3. Specify the device index. On a zForce Air the index is always 0.

The complete device address then evaluates to 0x40 0x02 0x02 0x00.

Encoding a Device Configuration Message

Device Configuration will be used as an example as it is a message that contains a large number of values with both context-specific primitive values and context-specific sequences..
Device Configuration ASN.1 Protocol  Expand source
– Instance specific settings for a device
               deviceConfiguration [APPLICATION 19] Sequence {
            – Set / get the number of touches to be tracked:
            numberOfTrackedTouches    [0] INTEGER (0..255) OPTIONAL,
            – Set / get the minimal distance for updating a tracked touch in move state
            trackingMinDistanceMove    [1] INTEGER (0..16383) OPTIONAL,
            -- Set / get the sub touch active area low bound in X coordinate
            subTouchActiveArea        [2] Sequence {
                – Write Request and Read Response only:
                – Set / get the sub touch active area low bound in X coordinate
                lowBoundX        [0] INTEGER (0..16383) OPTIONAL,
                – Set / get the sub touch active area low bound in Y coordinate
                lowBoundY        [1] INTEGER (0..16383) OPTIONAL,
                – Set / get the sub touch active area high bound in X coordinate
                highBoundX    [2] INTEGER (0..16383) OPTIONAL,
                – Set / get the sub touch active area high bound in Y coordinate
                highBoundY    [3] INTEGER (0..16383) OPTIONAL,
                – subTaa Reverse X coordinates, set / get true or false
                reverseX        [4] BOOLEAN OPTIONAL,
                – SubTaa Reverse Y coordinates, set / get true or false
                reverseY        [5] BOOLEAN OPTIONAL,
                – Flip x and y axis, set / get true or false
                flipXY            [6] BOOLEAN OPTIONAL,
                – Offset X coordinate
                offsetX            [7] INTEGER (0..32767) OPTIONAL,
                – Offset Y coordinate
                offsetY            [8] INTEGER (0..32767) OPTIONAL
            } OPTIONAL,
 
            – configure the reference signal setting
            referenceSignalConfig    [3] INTEGER (0..255) OPTIONAL,
 
            – Restriction of detected objects based on their size
            sizeRestriction [4] Sequence {
                maxSizeEnabled            [0] BOOLEAN OPTIONAL,
                maxSize                    [1] INTEGER (0..32767) OPTIONAL,
                minSizeEnabled            [2] BOOLEAN OPTIONAL,
                minSize                    [3] INTEGER (0..32767) OPTIONAL
            } OPTIONAL,
 
            – configure the detection mode
            – Standard modes increasing from 0, custom modes decreasing from 64
            – Giving an unlisted value will have no effect.
            detectionMode [5] INTEGER {
                – Reserved modes from (0) to (63) are listed below:
                default (0),        – finger and stylus are both enabled
                finger (1),
                – stylus (2),
 
                – Special modes for customized applications are listed below:
                mergeTouches (32), – merges all touch objects into one
                insensitiveFTIR (64)
            } OPTIONAL,
 
            – Set / get the number of touches to be reported:
            numberOfReportedTouches    [6] INTEGER (0..255) OPTIONAL,
 
            – Adapt active touch area to a HID display
            hidDisplaySize [7] Sequence {
                x    [0] INTEGER (0..32767) OPTIONAL,
                y    [1] INTEGER (0..32767) OPTIONAL
            } OPTIONAL
        } OPTIONAL,
All settings are optional and therefore does not require all settings to be defined in the message that is sent to the sensor.
We want to set the following settings in the sensor:
SubTouchActiveArea:

• LowBoundX: 500
• LowBoundY: 500
• HighBoundX: 2000
• HighBoundY: 2000

This is how to do it (the length bytes are represented by XX, and are added in the last step):