Parsers

LiCoRICE uses parsers to convert external buffers to internal signals and vice versa. This allows a 1-dimensional buffer passed into LiCoRICE through a driver to be treated as multiple n-dimensional signals. Or it can define how multiple signals are packed into a buffer for output. Parsers also allow the user to define a packet structure for their data which differs from the default. If no parser is specified, LiCoRICE expects there to be only one signal and for the buffer size and type to match that of the signal.

In general, parsers can be thought of as the tick-level code that runs for a source or sink, similar to the “user code” section of a module. LiCoRICE also provides the ability to add a constructor and a destructor to spin up and tear down resources needed to run the parser.

Source Parsers

In sources, the parser functions to convert the buffer supplied by the driver (inBuf) to a number of signals that can be used by LiCoRICE.

Consider the joystick_reader source taken from the joystick demo and defined below:

...

joystick_reader:
  language: python
  parser: True
  in:
    name: joystick_raw
    args:
      type: pygame_joystick
    schema:
      data:
        dtype: uint8
        size: 22
    async: True
  out:
    - joystick_axis
    - joystick_buttons

  ...

This source takes as input the external signal named joystick_raw which is a 22 element uint8 buffer supplied by the pygame_joystick driver. It has a parser, which is shown below:

joystick_axis[:] = [ (<double *>inBuf)[0], (<double *>inBuf)[1] ]
joystick_buttons[:] = [
    (<uint8_t *>inBuf)[128 + i] for i in range(joystick_buttons.size)
]

The format of inBuf is a mixed-type buffer with doubles representing the analog stick x- and y-coordinates followed by an array of enough uint8_ts to represent the joystick buttons. The parser first casts each of the analog stick coordinates from inBuf to double and packs them into the joystick_axis signal. It then casts each of the button values from inBuf to uint8_t and packs them into joystick_buttons. This way, the joystick_reader source can output a more readable data format than a flat buffer.

Sink Parsers

Sink parsers do more or less the opposite of source parsers, converting a number of LiCoRICE signals to a buffer that will be supplied to a driver for external output.