Kraken Z Image transfer protocol

Learning the basics

Messages are padded (empty bytes are added) to provide a consistent frame size.

• This process is called chunking - taking an infinite stream of 0's and 1', and breaking it into chunks for processing.
• if the message data is only 12 bytes long, we will add PAD_LENGTH - 12 more bytes to the end.
• Control messages are padded for 64 bytes, and "bulk" image transfers are 512.

The underlying USB driver, knows the packet/frame size.

The image transfer requires a series (sequence is important) of messages. Each message sent, has a matching response from the hardware. This 2-way communication is like a dance and the application software leads. If the complete specification of the protocol was available we would know how to dance in perfect unison with the hardware. WE DO NOT, so we step on the hardware shoes at times (metaphorically).

Data is formatted, format of the data is important.

A longer explanation can be found here For our understanding I will talk more specifically about the Kraken Z and Qt image formatting.

The Kraken Z LCD supports 24-bits of color 8R,8G,8B aka 24-bit RGB with 8 bits per channel like seen in the above image on the left.

However, the protocol expects a 32-bit ARGB image to be sent.

The Kraken Z will then ignore the alpha data sent and only grab the RGB from A-RGB.

Further more, Qt renders Qml into a 32-bit RGBA image when grabbing from the framebuffer (image generated from the live scene data).

An extra step is required to reorder (change the format) of the Qt framebuffer image from 32RGBA to 32ARGB for each frame sent to the LCD. Qt has a lot of built-in image classes and methods

The protocol

Each message in the sequence has a specific purpose of preparing the hardware. An ordered list will help keep it organized.

Important note before the protocol begins

1. Assume a byte array of 320 by 320 pixels - already converted to 32-ARGB. This array is 409,600 bytes long (32 x 320 x 320 / 8 ). IMAGE_DATA

   

   • That is quite a bit of data, and remember it will be sent in chunks of 512 bytes at a time. The image data alone will take 800 bulk transfers per image! This happens faster than the blink of an eye.

2. We cannot write to the same bucket that is being displayed by the device. The Kraken Device has 15 buckets (we believe). For our purpose, lets assume the current bucket is 1 and the TARGET_BUCKET is 0.

The protocol is described below in a pseudo code. LCD_CTRL is the control interface (endpoint address: 01 above) and LCD_DATA (endpoint address: 02 above) is the bulk transfer interface. You can reference the message CMD numbers here

// The process of selecting the bucket virtually, then deleting it  might not be necessary but we are still learning about the dance

LCD_CTRL.sendQueryBucket(TARGET_BUCKET); // 1. sets the "current" (virtual) index to the TARGET_BUCKET.
// Wait for response (about 10 milliseconds)
LCD_CTRL.sendDeleteBucket(TARGET_BUCKET); // 2. notifies to delete the data reference currently at the bucket (nulls the bucket).
// Wait for response (about 10 milliseconds)

// Work is still needed to understand this step, but below is my current understanding.
// END_BUCKET notifies how many buckets the image will take up (0, 1) for our needs
// MEMORY_START_ADDR is the physical offset of the bucket data
// MEMORY_SLOT_COUNT refers to how many 16-bit memory addresses will the image assume
LCD_CTRL.sendSetupBucket(TARGET_BUCKET, END_BUCKET, MEMORY_START_ADDR, MEMORY_SLOT_COUNT); // 3. Prepare the target bucket to hold our image.
// Wait for response (about 10 milliseconds)

LCD_CTRL.sendWriteStart(TARGET_BUCKET); // 4. notify the device to prepare for a new image on the bulk data path
// Wait for response (about 10 milliseconds)

// WRITE_MODE notifies the device to use index mode or asset ID mode (needs more research)
LCD_DATA.sendBulkDataInfo(WRITE_MODE, BYTE_COUNT); // 5. BYTE_COUNT is the number of bytes to expected in the image (409,600)
// Wait for response (about 10 milliseconds)

// It is important that no messages are sent to the control interface or the bulk interface, so we write the data synchronously.
LCD_DATA.writeDataSynchronous(IMAGE_DATA, BYTE_COUNT); // 6. will generate the 800 transfers sequentially

LCD_CTRL.sendWriteFinish(TARGET_BUCKET); // 7. notify the device the image is sent and the software is finished writing
// Wait for response (about 10 milliseconds)

// Optionally
LCD_CTRL.sendSwitchBucket(TARGET_BUCKET); // notify the LCD to now display the image just written.