Customer Documentation: Neonode® Touch Sensor Module User's Guide : .ASN.1 PDU Examples in GSER Notation v1.6

The ASN.1 PDU examples are encoded according to the man-readable Generic String Encoding Rules (GSER), as both the information in the PDU definition file and the messages encoded according to DER can be difficult to read for a human.

The following examples are available: 

A short introduction to the GSER notation:

• Sequences and/or sets (items containing sub items) are shown as curly brackets: { _}
• 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  

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 ,  
        
         }
        

response: {  deviceAddress ,  }

notification: {  deviceAddress ,  
        
          notificationTimestamp 
         
          }
         
        

Where

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

   

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

• Timestamp is an integer representing int16 counting at 32768 Hz.

• The deviceInformation command fetches for example the product id and the FW version. What information that is available differs depending on the type of device. The following example shows a response from a platform device.

  request command

    deviceInformation {  }

  command response

    deviceInformation {    platformInformation {      platformVersionMajor 7,      platformVersionMinor 0,      protocolVersionMajor 1,      protocolVersionMinor 5,      firmwareVersionMajor 1,      firmwareVersionMinor 0,      hardwareIdentifier "Demo board",      hardwareVersion "R2",      asicType nn1002,      numberOfAsics 1,      mcuUniqueIdentifier '340038000E51333439333633'H,      projectReference "DEMO_1.0_REL",      platformReference "734cebd",      buildTime "16:01:14",      buildDate "2016-07-01"    	}  }

  The fields have the following meaning:

  • platformVersion: FW platform version, version 7.0 in the example.
  • protocolVersion: communication protocol version, version 1.5 in the example.
  • firmwareVersion: product FW version, version 1.0 in the example.
  • hardware: product hardware, configuration and revision.
  • asicType: which type of the Neonode optical scanner ASIC is used, and count.
  • mcuUniqueIdentifier: identifier created at mcu manufacturing.
  • projectReference: FW GIT tags or hashes. Product specific. Uniquely identifies the FW revision.
  • platformReference: FW GIT tags or hashes. Uniquely identifies generic firmware base commit for the platform.
  • buildTime: time of build in Central European Time, a string.
  • buildDate: date of build, a string. 

The deviceInformation command fetches for example the product id and the FW version. What information that is available differs depending on the type of device. The following example shows a response from a platform device.

  deviceInformation {  }

  deviceInformation {    platformInformation {      platformVersionMajor 7,      platformVersionMinor 0,      protocolVersionMajor 1,      protocolVersionMinor 5,      firmwareVersionMajor 1,      firmwareVersionMinor 0,      hardwareIdentifier "Demo board",      hardwareVersion "R2",      asicType nn1002,      numberOfAsics 1,      mcuUniqueIdentifier '340038000E51333439333633'H,      projectReference "DEMO_1.0_REL",      platformReference "734cebd",      buildTime "16:01:14",      buildDate "2016-07-01"    	}  }

The fields have the following meaning:

• platformVersion: FW platform version, version 7.0 in the example.
• protocolVersion: communication protocol version, version 1.5 in the example.
• firmwareVersion: product FW version, version 1.0 in the example.
• hardware: product hardware, configuration and revision.
• asicType: which type of the Neonode optical scanner ASIC is used, and count.
• mcuUniqueIdentifier: identifier created at mcu manufacturing.
• projectReference: FW GIT tags or hashes. Product specific. Uniquely identifies the FW revision.
• platformReference: FW GIT tags or hashes. Uniquely identifies generic firmware base commit for the platform.
• buildTime: time of build in Central European Time, a string.
• buildDate: date of build, a string. 

The frequency command changes the update frequency of all touch sensors globally, that is for all devices on all platforms.

The following update frequencies can be set, if enabled in the product:

• finger: activated when objects with characteristics matching regular fingers are detected.
• stylus: activated for narrow stylus-like objects. (Not enabled for the zForce AIR touch sensor.)
• idle: activated when no objects are detected, in order to minimize power usage.

The unit is Hz.

  frequency {    finger 30,    idle 10  }

The response contains the current frequency settings of the product:

  frequency {    finger 30,    idle 10  }

In this example, the touch sensor update frequency will be 30 Hz as long as finger-like objects were recently detected. When no objects are detected, the frequency will drop to 10 Hz.

There are a number of different touch sensor products that can co-exist on the same physical device. There are some product-specific commands, but the ones listed here are general.

The zForce AIR Touch Sensor will be used as example, which means the device address will be that of the first zForce Air virtual device

'0200'H

The operationMode command sets what processing to perform on sensor signals, and what diagnostics that are exposed.

The following example sets the operation mode to normal object detection:

  operationMode {    detection TRUE,    signals FALSE,    ledLevels FALSE,    detectionHid FALSE,    gestures FALSE  }

  operationMode {    detection TRUE,    signals FALSE,    ledLevels FALSE,    detectionHid FALSE  }

The touchFormat command retrieves the binary format of the detected objects. 

  touchFormat {  }

  touchFormat {    touchDescriptor { id, event, loc-x-byte1, loc-x-byte2, loc-y-byte1, loc-y-byte2, size-x-byte1, size-y-byte1 }  }

The touchDescriptor is a bit string, where each bit signifies one byte of payload being included in the touchNotification octet strings. A touchNotification is the concatenation of those bytes. The following table lists all bits. Bits used in the example are marked green.

Location and size coordinates can be specified with up to 3 bytes. The byte order in decreasing significance - big-endian. For example:

• 1 byte: location x = loc-x-byte1
• 2 bytes: location x = (loc-x-byte1 << 8) + loc-x-byte2
• 3 bytes: location x = (loc-x-byte1 << 16) + (loc-x-byte2 << 8) + loc-x-byte3

Location is signed, and size is not.

The location coordinate scale is one of two systems, depending on which detector is used:

• Physical: Robair Air and Core detectors: The unit is 0.1 mm. A coordinate value of 463 thus means 46.3 mm from origin.
• Relative: Triangles and Shape Air detectors: Fraction of the largest screen dimension as fixed point with 14 bits after the radix point (q14). On a widescreen display, the horizontal axis ranges [0, 2¹⁴[, and vertical [0, 2¹⁴ * 9/16[ ([0, 16383], [0, 9215]).

Size is in mm.

Confidence and pressure are fractions of the full values, in percent.

The enable command activates the touch sensor, and notifications of detections start to stream.

  enable {    enable 0  }

  enable {    enable  }

To deactivate the touch sensor, send the disable command:

  enable {    disable NULL  }

  enable {    disable NULL  }

A detected object is reported with a touchNotification. The touchNotification payload is a touchDescriptor bit string. Every concurrently tracked object is represented by its own touchNotification payload.

notificationMessage touchNotifications: {    '0001013600730A0A64'H  },

The following table shows the value of the example payload interpreted with the touch descriptor.  

The touchNotification is from a Core device and translates to "Object 0 moved. Location is (31.0, 11.5) mm. Size is 10x10 mm."

The command deviceInformation retrieves some information about the virtual device instance.

  deviceInformation {  }

  deviceInformation {    deviceInstanceInformation {      productVersionMajor 1,      productVersionMinor 38,      physicalWidth 1584,      physicalHeight 1341,      numberOfSignalAxes 0    }  }

The response contains the deviceInstanceInformation structure, with the following parts:

Some configurations of the touch sensor device can be changed at run-time. The deviceConfiguration request command and command response are identical, except some configuration items in the request may be omitted in order to leave them in their current state.

For instance, to set object size restrictions only, omit all other items:

  deviceConfiguration {    sizeRestriction {      maxSizeEnabled TRUE,      maxSize 100,      minSizeEnabled FALSE    }  }

The command response contains the state of all configuration items:

  deviceConfiguration {    subTouchActiveArea {      lowBoundX 0,      lowBoundY 0,      highBoundX 1584,      highBoundY 1341,      reverseX FALSE,      reverseY FALSE,      flipXY FALSE,      offsetX 0,      offsetY 0    },    sizeRestriction {      maxSizeEnabled FALSE,      maxSize 0,      minSizeEnabled FALSE,      minSize 0    },    detectionMode default,    numberOfReportedTouches 2,    hidDisplaySize {      x 1584,      y 1341    }  }

The items are:

• subTouchActiveArea: Crop the touch sensor to a rectangle between the specified low and high coordinates in each dimension. Offset can be applied and flip the X and Y axis. Origin of reported locations is set to low coordinates, or if reversed, the high coordinate with increasing coordinates toward low.
• sizeRestriction: Limit detection to objects within this size range. Unit is 0.1 mm.
• detectionMode, one of the following:
  • default: finger and stylus
  • finger: Finger only
  • mergeTouches: Merges all touch objects into one
  • insensitiveFTIR: Unsupported
• numberOfReportedTouches: Maximum number of reported tracked objects.
• hidDisplaySize: Scaling the coordinate system when using the sensor in HID Touch Digitizer mode.