LaserBox/Formats and Protocols

From Hackstrich
Revision as of 00:49, 17 March 2017 by SarahEmm (talk | contribs) (Adding info on serial debug protocol.)

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 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
      • Response - TBD
  • LaserBox to PC
    • All messages begin with one byte:
      • 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 which is command-dependent and detailed above.