### Command Protocol

Source: https://context7.com/frameworkcomputer/dotmatrixtool/llms.txt

Sends commands to the LED Matrix module using a binary protocol. All commands start with a magic header (0x32, 0xAC), followed by a command ID and parameters. The protocol supports various operations including brightness control, pattern display, sleep mode, and firmware updates.

```APIDOC
## Command Protocol

### Description
Sends commands to the LED Matrix module using a binary protocol. All commands start with a magic header (0x32, 0xAC), followed by a command ID and parameters. The protocol supports various operations including brightness control, pattern display, sleep mode, and firmware updates.

### Method
`async command(port, id, params)`

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **port** (object) - The serial port object.
- **id** (number) - The command ID.
- **params** (array or number) - Command parameters.

### Request Example
```javascript
// Command IDs
const BRIGHTNESS_CMD = 0x00;    // Set brightness (0-255)
const PATTERN_CMD = 0x01;       // Display preset pattern
const BOOTLOADER_CMD = 0x02;    // Enter bootloader mode
const SLEEP_CMD = 0x03;         // Sleep/wake control
const DRAW_CMD = 0x06;          // Draw custom bitmap
const VERSION_CMD = 0x20;       // Query firmware version

// Example: Set brightness to 128 (50%)
await command(portLeft, BRIGHTNESS_CMD, 128);

// Example: Wake device
await command(portLeft, SLEEP_CMD, [0]);  // 0 = wake, 1 = sleep
```

### Response
#### Success Response (200)
None (Commands are sent, no direct response parsing in this function).

#### Response Example
None
```

--------------------------------

### Send Commands to LED Matrix Module (JavaScript)

Source: https://context7.com/frameworkcomputer/dotmatrixtool/llms.txt

Sends commands to the LED Matrix module using a binary protocol. Commands start with a magic header (0x32, 0xAC), followed by a command ID and parameters. This function supports various operations like brightness control, pattern display, sleep mode, and firmware updates. It constructs the command packet and writes it to the serial port.

```javascript
// Command IDs
const BRIGHTNESS_CMD = 0x00;    // Set brightness (0-255)
const PATTERN_CMD = 0x01;       // Display preset pattern
const BOOTLOADER_CMD = 0x02;    // Enter bootloader mode
const SLEEP_CMD = 0x03;         // Sleep/wake control
const DRAW_CMD = 0x06;          // Draw custom bitmap
const VERSION_CMD = 0x20;       // Query firmware version

// Send a command to the device
async function command(port, id, params) {
  const writer = port.writable.getWriter();

  // Build command packet: [magic header, command ID, params...]
  let bytes = [0x32, 0xAC];
  bytes = bytes.concat([id]);
  bytes = bytes.concat(params);

  const data = new Uint8Array(bytes);
  await writer.write(data);
  writer.releaseLock();
}

// Example: Set brightness to 128 (50%)
await command(portLeft, BRIGHTNESS_CMD, 128);

// Example: Wake device
await command(portLeft, SLEEP_CMD, [0]);  // 0 = wake, 1 = sleep
```

--------------------------------

### Firmware Version Query

Source: https://context7.com/frameworkcomputer/dotmatrixtool/llms.txt

Queries and parses the firmware version from a connected LED Matrix module. The response contains major, minor, patch version numbers and a pre-release flag.

```APIDOC
## Firmware Version Query

### Description
Queries and parses the firmware version from a connected LED Matrix module. The response contains major, minor, patch version numbers and a pre-release flag.

### Method
`async checkFirmwareVersion(port, side)`

### Endpoint
N/A (Internal function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **port** (object) - The serial port object.
- **side** (string) - Identifier for the matrix side ('left' or 'right').

### Request Example
```javascript
async function checkFirmwareVersion(port, side) {
  const writer = port.writable.getWriter();
  const reader = port.readable.getReader();

  // Send version query command
  const data = new Uint8Array([0x32, 0xAC, 0x20]);
  await writer.write(data);
  writer.releaseLock();

  // Read response
  const { value, done } = await reader.read();

  // Parse version bytes
  const major = value[0];
  const minor = (value[1] & 0xF0) >> 4;
  const patch = value[1] & 0x0F;
  const pre_release = value[2] == 1;

  console.log(`Firmware: ${major}.${minor}.${patch} Pre-release: ${pre_release}`);

  reader.releaseLock();
}
```

### Response
#### Success Response (200)
- Console logs the firmware version (e.g., "Firmware: 0.1.5 Pre-release: false").

#### Response Example
```
Firmware: 0.1.5 Pre-release: false
```
```

--------------------------------

### Define and Apply LED Matrix Patterns

Source: https://context7.com/frameworkcomputer/dotmatrixtool/llms.txt

Provides a system for generating preset patterns on the LED matrix. Patterns can be defined using an `each` function for simple pixel-by-pixel logic or a `fn` function for more complex, stateful pattern generation. The `drawPattern` function applies these patterns to a given matrix and updates the display.

```javascript
const patterns = {
  // Simple patterns using each() - returns 0 (on) or 1 (off)
  Blank: {
    each: (row, col) => 1,  // All pixels off
  },
  Full: {
    each: (row, col) => 0,  // All pixels on
  },
  'Checkerboard': {
    each: (row, col) => (row % 2 < 1) ? (col + 1) % 2 < 1 : col % 2 < 1,
  },
  'Every 2nd Row': {
    each: (row, col) => row % 2 !== 0,
  },
  'Diagonal Lines': {
    each: (row, col) => Math.floor((row + col) / 1) % 2 == 0,
  },
  'Diamond Pattern': {
    each: (row, col) => {
      const size = 5;
      const repeatHeight = 10;
      const centerCol = Math.floor(WIDTH / 2);
      const adjustedRow = row % repeatHeight;
      const centerRow = Math.floor(repeatHeight / 2);
      return Math.abs(adjustedRow - centerRow) + Math.abs(col - centerCol) < size;
    },
  },
  // Complex pattern using fn() for random scatter
  'Scatter 50%': {
    fn: ({ matrix }) => {
      for (let row = 0; row < HEIGHT; row++)
        for (let col = 0; col < WIDTH; col++)
          matrix[row][col] = 1;  // Start blank

      const count = Math.floor((WIDTH * HEIGHT) / 2);
      let placed = 0;
      while (placed < count) {
        const row = Math.floor(Math.random() * HEIGHT);
        const col = Math.floor(Math.random() * WIDTH);
        if (matrix[row][col] === 1) {
          matrix[row][col] = 0;
          placed++;
        }
      }
    },
  },
};

// Apply pattern to matrix and update display
function drawPattern(matrix, patternName, pos) {
  if (patterns[patternName].each) {
    for (let col = 0; col < WIDTH; col++) {
      for (let row = 0; row < HEIGHT; row++) {
        matrix[row][col] = patterns[patternName].each(row, col);
      }
    }
  } else if (patterns[patternName].fn) {
    patterns[patternName].fn({ matrix });
  }
  updateMatrix(matrix, pos);
}

// Usage: Apply checkerboard to left matrix
drawPattern(matrix_left, 'Checkerboard', 'left');
await sendToDisplayLeft();
```

--------------------------------

### Establish Serial Connection to LED Matrix Module (JavaScript)

Source: https://context7.com/frameworkcomputer/dotmatrixtool/llms.txt

Establishes a serial connection to a Framework LED Matrix Input Module using the browser's Web Serial API. It requests port selection, opens the serial port with a baud rate of 115200, and queries the firmware version upon successful connection. This function is intended to be called when a user initiates a connection, typically via a button click.

```javascript
async function connectSerialLeft() {
  // Request port selection from user
  portLeft = await navigator.serial.requestPort();

  const { usbProductId, usbVendorId } = portLeft.getInfo();
  console.log(`VID:PID ${usbVendorId}:${usbProductId}`);

  // Open the port if not already open
  if (portLeft.readable === null || portLeft.writeable === null) {
    await portLeft.open({ baudRate: 115200 });
  }

  // Query and display firmware version
  await checkFirmwareVersion(portLeft, 'left');
}

// Usage: Called when user clicks "Connect Left" button
$('#connectLeftBtn').click(connectSerialLeft);
// Expected output: Console shows "VID:PID 12972:33" and firmware version is displayed
```

--------------------------------

### Initialize and Prepare Matrix Data for Drawing

Source: https://context7.com/frameworkcomputer/dotmatrixtool/llms.txt

Manages a 9x34 pixel LED matrix, storing pixels as 0 (on) or 1 (off). It provides functions to create an empty matrix, initialize matrices, and prepare pixel data into a 39-byte bitmap for transmission to the physical display.

```javascript
const WIDTH = 9;
const HEIGHT = 34;

// Create empty matrix (all pixels off)
function createArray(height, width) {
  var arr = new Array(height);
  for (let i = 0; i < height; i++) {
    arr[i] = new Array(width).fill(1);  // 1 = off
  }
  return arr;
}

// Initialize matrices for left and right modules
var matrix_left = createArray(34, 9);
var matrix_right = createArray(34, 9);

// Prepare matrix data for serial transmission
function prepareValsForDrawingLeft() {
  let vals = new Array(39).fill(0);

  for (let col = 0; col < WIDTH; col++) {
    for (let row = 0; row < HEIGHT; row++) {
      if (matrix_left[row][col] == 0) {  // Pixel is ON
        const i = col + row * WIDTH;
        vals[Math.trunc(i/8)] |= 1 << i % 8;
      }
    }
  }
  return vals;
}

// Send matrix to physical device
async function sendToDisplayLeft() {
  if (portLeft === null) return;
  let vals = prepareValsForDrawingLeft();
  await command(portLeft, DRAW_CMD, vals);
}
```

--------------------------------

### Query and Parse Firmware Version from LED Matrix Module (JavaScript)

Source: https://context7.com/frameworkcomputer/dotmatrixtool/llms.txt

Queries and parses the firmware version from a connected LED Matrix module. It sends a version query command (0x20) and then reads the response from the serial port. The response is parsed to extract the major, minor, patch version numbers, and a pre-release flag. This function is crucial for verifying device compatibility and status.

```javascript
async function checkFirmwareVersion(port, side) {
  const writer = port.writable.getWriter();
  const reader = port.readable.getReader();

  // Send version query command
  const data = new Uint8Array([0x32, 0xAC, 0x20]);
  await writer.write(data);
  writer.releaseLock();

  // Read response
  const { value, done } = await reader.read();

  // Parse version bytes
  const major = value[0];
  const minor = (value[1] & 0xF0) >> 4;
  const patch = value[1] & 0x0F;
  const pre_release = value[2] == 1;

  console.log(`Firmware: ${major}.${minor}.${patch} Pre-release: ${pre_release}`);
  // Expected output: "Firmware: 0.1.5 Pre-release: false"

  reader.releaseLock();
}
```

--------------------------------

### Serial Connection API

Source: https://context7.com/frameworkcomputer/dotmatrixtool/llms.txt

Establishes a serial connection to a Framework LED Matrix Input Module through the browser's Web Serial API. The connection uses 115200 baud rate and automatically queries the firmware version upon successful connection.

```APIDOC
## Serial Connection API

### Description
Establishes a serial connection to a Framework LED Matrix Input Module through the browser's Web Serial API. The connection uses 115200 baud rate and automatically queries the firmware version upon successful connection.

### Method
`async`

### Endpoint
`navigator.serial.requestPort()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
// Connect to a LED Matrix Input Module
async function connectSerialLeft() {
  // Request port selection from user
  portLeft = await navigator.serial.requestPort();

  const { usbProductId, usbVendorId } = portLeft.getInfo();
  console.log(`VID:PID ${usbVendorId}:${usbProductId}`);

  // Open the port if not already open
  if (portLeft.readable === null || portLeft.writeable === null) {
    await portLeft.open({ baudRate: 115200 });
  }

  // Query and display firmware version
  await checkFirmwareVersion(portLeft, 'left');
}

// Usage: Called when user clicks "Connect Left" button
$('#connectLeftBtn').click(connectSerialLeft);
```

### Response
#### Success Response (200)
- `portLeft` (object) - The connected serial port object.
- Console logs VID:PID and firmware version.

#### Response Example
```
VID:PID 12972:33
Firmware: 0.1.5 Pre-release: false
```
```

--------------------------------

### Adjust LED Brightness (JavaScript)

Source: https://context7.com/frameworkcomputer/dotmatrixtool/llms.txt

Allows real-time adjustment of LED brightness from 0 (dimmest) to 255 (brightest). It listens for input events on a range slider and sends the brightness value to both LED matrix modules using a predefined `BRIGHTNESS_CMD`. Requires a `port` object and the `command` function.

```javascript
// Brightness slider handler
$(document).on('input change', '#brightnessRange', function() {
  let brightness = $(this).val();  // 0-255

  // Send brightness command to both modules
  command(portLeft, BRIGHTNESS_CMD, brightness);
  command(portRight, BRIGHTNESS_CMD, brightness);
});

// HTML slider element
// <input type="range" id="brightnessRange" min="0" max="255">
```

--------------------------------

### Control Device Power State (JavaScript)

Source: https://context7.com/frameworkcomputer/dotmatrixtool/llms.txt

Manages the sleep/wake state and bootloader mode of LED Matrix modules. It utilizes a generic `sendCommand` function to send specific commands (0x03 for sleep/wake, 0x02 for bootloader) to the device via the Web Serial API. Requires a `port` object representing the serial connection.

```javascript
async function wake(port, shouldWake) {
  // SLEEP_CMD (0x03): param 0 = wake, param 1 = sleep
  await sendCommand(port, 0x03, [shouldWake ? 0 : 1]);
}

// Enter bootloader mode for firmware updates
async function bootloader(port) {
  await sendCommand(port, 0x02, [0]);
}

// Generic command sender
async function sendCommand(port, commandId, params) {
  if (port === null) return;

  const writer = port.writable.getWriter();
  let bytes = [0x32, 0xAC, commandId].concat(params);
  await writer.write(new Uint8Array(bytes));
  writer.releaseLock();
}

// Usage examples:
// Wake both matrices
$('#wakeBtn').click(function() {
  wake(portLeft, true);
  wake(portRight, true);
});

// Put both matrices to sleep
$('#sleepBtn').click(function() {
  wake(portLeft, false);
  wake(portRight, false);
});

// Enter bootloader on both devices
$('#bootloaderBtn').click(function() {
  bootloader(portLeft);
  bootloader(portRight);
});
```

--------------------------------

### Handle Mouse Events for Interactive LED Matrix Drawing

Source: https://context7.com/frameworkcomputer/dotmatrixtool/llms.txt

Manages mouse events to enable real-time drawing on the LED matrix grids. It interprets left-clicks as drawing actions (turning pixels on) and right-clicks or Ctrl+left-clicks as erase actions (turning pixels off). Events are bound to table cells, and the display is updated immediately after each interaction.

```javascript
function toggleLeft(e) {
  var x = $(this).data('i');  // Row index
  var y = $(this).data('j');  // Column index

  if (e.buttons == 1 && !e.ctrlKey) {
    // Left click: draw (pixel on = 0)
    matrix_left[x][y] = 0;
    $(this).addClass('off');
  }
  else if (e.buttons == 2 || (e.buttons == 1 && e.ctrlKey)) {
    // Right click or Ctrl+left: erase (pixel off = 1)
    matrix_left[x][y] = 1;
    $(this).removeClass('off');
  }

  // Immediately sync to hardware
  sendToDisplay(true);
  return false;
}

// Bind events to table cells
$table_left.on("mousedown", "td", toggleLeft);
$table_left.on("mouseenter", "td", toggleLeft);  // Drag drawing
$table_left.on("dragstart", function() { return false; });
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.