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.

• PC to LaserBox
  • N - NoOp - Do nothing, continue on.
    • Response - 'OK'
  • L - Live Mode - Begin receiving Pattern File Format v2 data and displaying it live as it it had been read from a file. Returns to this protocol when the Exit Interpreter pattern command is received.
  • S - Status - Output current system status.
    • Response - A bunch of status text intended for humans including current time, cell backhaul status, and resource levels.
  • T - Run Test - Run a self-test procedure.
    • Parameter 1 - 1 character - Which test to run:
      • T - Telemetry (cell backhaul) test
      • S - Storage test
      • G - Sensor test
      • L - Laser test
      • F - Fog test
    • Response - 'OK' or 'FAIL'
  • V - Toggle Verbose Mode - Switch verbose output on or off.
• LaserBox to PC
  • All messages begin with a type character:
    • 'U' - Unsolicited Message - Not a response to a command, this is a status being sent out for debug purposes.
    • 'R' - Solicited Response - This is a response to a command. The format of the response is command-dependent and defined above.
  • Followed by a line indicator character:
    • '+' - Interim line of the given message, not the last one.
    • '-' - Last line of the given message.