Difference between revisions of "LaserBox/Formats and Protocols"

From Hackstrich
(Changing Load Pixel & Refresh to pack all data into one byte instead of using 4 where 1 would do.)
(Adding info on serial debug protocol.)
Line 50: Line 50:
 
** 0x04 - Refresh All Planes - Push loaded pixel data from the hold registers to the laser outputs.
 
** 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.
 
** 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.

Revision as of 00:49, 17 March 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.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.