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.LBP
  • 2.LBP
  • 3.LBP
• DOWN
  • 1.LBP
• LEFT
  • 1.LBP
  • 2.LBP
• RIGHT
  • 1.LBP
  • 2.LBP
  • 3.LBP
  • 4.LBP
• LASERBOX.LOG

Pattern File Format v1

This is the first version of the pattern file format, which is effectively obsolete as of 2017-02-02 as the pattern editor now saves and loads v2 format files. This was the only file format supported by the editor in the past, and is still supported for backwards compatibility. The extension used for this format is PAT. 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 version of the file format that LaserBox hardware can read, and the pattern editor tool can read and write. The extension used for this format is LBP (LaserBox Pattern) Pattern files consist of the following:

• 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 1a - 1 bit (MSB) - Plane to load (0 = ZY, 1 = XY)
    • Parameter 1a - 3 bits - Row to load
    • Parameter 1a - 3 bits - Column to load
    • Parameter 1a - 1 bit (LSB) - 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.

Serial Debug Protocol

The USB serial port on the Arduino is used for debugging and status reporting purposes during build and setup. It was originally a single-byte based command system, but is now a full hierarchical menu. Press ENTER (NL, \n) after connecting to launch the system.