LaserBox/Formats and Protocols

This page documents the formats and protocols used in the LaserBox project.

Filesystem Layout

The patterns are stored on an SD card, formatted as FAT16.

Overview

• Root directory holds one directory for each gesture
  • Under each gesture directory, there are numbered pattern files that are chosen randomly each time
• Root directory also holds LASERBOX.LOG which is written to when any events happen

Example

• UP
  • 1.PAT
  • 2.PAT
  • 3.PAT
• DOWN
  • 1.PAT
• LEFT
  • 1.PAT
  • 2.PAT
• RIGHT
  • 1.PAT
  • 2.PAT
  • 3.PAT
  • 4.PAT
• LASERBOX.LOG

Pattern File Format v1

This is the first version of the pattern file format, which is currently in use as of 2017-03-16. Pattern files consist of the following:

• Number of frames in file (one byte)
• Frame data for first frame (12 bytes, 6 per plane)
• Frame data for second frame (12 bytes, 6 per plane)
• ...
• Frame data for last frame (12 bytes, 6 per plane)

Pattern File Format v2

This is the planned next version of the pattern file format, to be implemented soon if time allows. Pattern files consist of the followng:

• Magic string 'PATv2'
• One or more of the following blocks:
  • 0x00 - NoOp - Do nothing, continue on.
  • 0x01 - Delay - Wait a certain amount of time before continuing on.
    • Parameter 1 - 1 byte - Number of milliseconds * 10 to delay (i.e. 25 = 250ms)
  • 0x02 - Load Plane - Load pixel data into a given plane.
    • Parameter 1 - 1 byte - Plane to load (0 = ZY, 1 = XY)
    • Parameter 2 - 6 bytes - Pixel data (each byte is one row, last two bits of each byte are ignored)
  • 0x03 - Load Pixel & Refresh - Load pixel data into a single pixel, then refresh all planes.
    • Parameter 1 - 1 Byte - Plane to load (0 = ZY, 1 = XY)
    • Parameter 2 - 1 Byte - Column to load
    • Parameter 3 - 1 Byte - Row to load
    • Parameter 4 - 1 Byte - Pixel state
  • 0x04 - Refresh All Planes - Push loaded pixel data from the hold registers to the laser outputs.
  • 0xFF - Exit Interpreter - If encountered in a file, cease parsing at that point. If in a live serial stream, drop out of live mode.