Difference between revisions of "LaserBox/Formats and Protocols"

From Hackstrich
(Created page with "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 ==...")
 
(Rolling back adding the config directory, decided to go a simpler route for config.)
 
(12 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
== Filesystem Layout ==
 
== Filesystem Layout ==
 
The patterns are stored on an SD card, formatted as FAT16.
 
The patterns are stored on an SD card, formatted as FAT16.
 +
 
=== Overview ===
 
=== Overview ===
 
* Root directory holds one directory for each gesture
 
* Root directory holds one directory for each gesture
Line 10: Line 11:
 
=== Example ===
 
=== Example ===
 
* UP
 
* UP
** 1.PAT
+
** 1.LBP
** 2.PAT
+
** 2.LBP
** 3.PAT
+
** 3.LBP
 
* DOWN
 
* DOWN
** 1.PAT
+
** 1.LBP
 
* LEFT
 
* LEFT
** 1.PAT
+
** 1.LBP
** 2.PAT
+
** 2.LBP
 
* RIGHT
 
* RIGHT
** 1.PAT
+
** 1.LBP
** 2.PAT
+
** 2.LBP
** 3.PAT
+
** 3.LBP
** 4.PAT
+
** 4.LBP
 
* LASERBOX.LOG
 
* LASERBOX.LOG
  
 
=== Pattern File Format v1 ===
 
=== 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:
+
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)
 
* Number of frames in file (one byte)
 
* Frame data for first frame (12 bytes, 6 per plane)
 
* Frame data for first frame (12 bytes, 6 per plane)
Line 34: Line 35:
  
 
=== Pattern File Format v2 ===
 
=== 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:
+
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'
 
* Magic string 'PATv2'
 
* One or more of the following blocks:
 
* One or more of the following blocks:
 
** 0x00 - NoOp - Do nothing, continue on.
 
** 0x00 - NoOp - Do nothing, continue on.
 
** 0x01 - Delay - Wait a certain amount of time before continuing 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)
+
*** Parameter 1 - 1 byte - Number of milliseconds * 10 to delay (i.e. 25 = 250ms)
 
** 0x02 - Load Plane - Load pixel data into a given plane.
 
** 0x02 - Load Plane - Load pixel data into a given plane.
*** Parameter 1 - 1 Byte - Plane to load (0 = ZY, 1 = XY)
+
*** 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)
 
*** Parameter 2 - 6 bytes - Pixel data (each byte is one row, last two bits of each byte are ignored)
** 0x03 - Refresh All Planes - Push loaded pixel data from the hold registers to the laser outputs.
+
** 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.

Latest revision as of 22:56, 16 April 2017

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.