### USB Setup Transaction Handling (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Modifies the handling of SETUP transactions to prevent NAK responses. This is achieved by ensuring the receive buffer is empty when SETUP tokens are expected, preventing zero-sized data packets from being passed to usbPoll() during the status phase.

```c
  - We must not reply with NAK to a SETUP transaction. We can only achieve this
    by making sure that the rx buffer is empty when SETUP tokens are expected.
    We therefore don't pass zero sized data packets from the status phase of
    a transfer to usbPoll(). This change MAY cause troubles if you rely on
    receiving a less than 8 bytes long packet in usbFunctionWrite() to
    identify the end of a transfer. usbFunctionWrite() will NEVER be called
    with a zero length.
```

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

### USB Configuration Prototype File (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Includes a template configuration file named usbconfig-prototype.h. This file serves as a starting point for users to create their own usbconfig.h file, outlining the available configuration options.

```c
  - Added template usbconfig.h file under the name usbconfig-prototype.h
```

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

### USB Vendor Request Handling (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Modifies the interface for handling vendor-specific setup requests via the usbVendorSetup() function. This change is part of the ongoing refinement of the USB driver's communication protocols.

```c
  - Changed interface for usbVendorSetup().
```

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

### USB Default Vendor and Product IDs (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Adds the use of default Vendor and Product IDs obtained from voti.nl. This simplifies the initial setup for users by providing readily available IDs, along with a license file outlining usage rules.

```c
  - Added (free) default Vendor- and Product-IDs bought from voti.nl.
  - Added USBID-License.txt file which defines the rules for using the free
    shared VID/PID pair.
```

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

### Configure USB RX Buffer Memory Section (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Defines how to specify the memory section for the USB receive buffer using the USB_BUFFER_SECTION configuration variable. It emphasizes the constraint that the buffer must not cross 256-byte page boundaries and provides an example linker option.

```c
#define USB_BUFFER_SECTION    ".mybuffer"
// Example linker option:
// -Wl,--section-start=.mybuffer=0x800060
```

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

### Write Extended Configuration Data to EEPROM (C)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

Writes 32 bytes of custom configuration data to EEPROM using HID report ID 3. The firmware writes this data to EEPROM starting at offset 64. This is useful for storing application-specific settings.

```c
// HID Feature Report 3: Write extended data (33 bytes)
unsigned char config_data[33];
config_data[0] = 3;  // Report ID

// Example: Store custom configuration
config_data[1] = 0x01;  // Version
config_data[2] = 0x05;  // Mode
config_data[3] = 100;   // Brightness
// ... fill remaining 29 bytes ...
memset(&config_data[4], 0, 29);

int result = hid_send_feature_report(device, config_data, sizeof(config_data));

if (result > 0) {
    printf("Configuration written to EEPROM\n");
}

// Firmware writes to EEPROM starting at offset 64
// Useful for application-specific settings
// (main.cpp:262-268)

```

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

### Set LED Color via HID Feature Report (C)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

This example shows how to set the LED color (Red, Green, Blue) using a HID SET_REPORT request with report ID 1. The host sends a 4-byte buffer containing the report ID and the desired color values. The firmware then processes these bytes to update the PWM outputs. This can be done using libraries like hidapi or libusb.

```c
// HID Feature Report 1: Set device colors (4 bytes)
// [Report ID (1)] [Red] [Green] [Blue]

unsigned char color_data[4] = {
    0x01,  // Report ID
    255,   // Red channel (0-255)
    64,    // Green channel (0-255)
    192    // Blue channel (0-255)
};

// Send using hidapi
int result = hid_send_feature_report(device, color_data, sizeof(color_data));

// Or using libusb control transfer
usb_control_msg(
    dev_handle,
    USB_TYPE_CLASS | USB_RECIP_INTERFACE | USB_ENDPOINT_OUT,
    USBRQ_HID_SET_REPORT,
    (3 << 8) | 1,  // Report Type Feature (3), Report ID 1
    0,             // Interface
    color_data,
    4,
    5000
);

// The firmware receives 3 bytes after report ID and applies to PWM
// (main.cpp:115-122, 250-254)
```

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

### Get Current LED Color State (HID GET_REPORT)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

Retrieve the current RGB color values being displayed by the LED. This is achieved by sending a HID GET_REPORT request with report ID 1.

```APIDOC
## GET CURRENT LED COLOR STATE (HID GET_REPORT)

### Description
Reads the current Red, Green, and Blue values from the BlinkStick device using a HID GET_REPORT request with report ID 1.

### Method
HID GET_REPORT

### Endpoint
N/A (handled via HID API)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// HID Feature Report 1: Current device colors (4 bytes expected response)
// [Report ID (1)] [Red] [Green] [Blue]

unsigned char buffer[4];
// Using hidapi library:
int result = hid_get_feature_report(device, buffer, sizeof(buffer));

if (result > 0) {
    // buffer[0] should be 1 (report ID)
    printf("Current color - R:%d G:%d B:%d\n",
           buffer[1], buffer[2], buffer[3]);
}
```

### Response
#### Success Response (200)
- **report_id** (byte) - Always 1 for this report.
- **red** (byte) - The current red channel value (0-255).
- **green** (byte) - The current green channel value (0-255).
- **blue** (byte) - The current blue channel value (0-255).

#### Response Example
```json
{
  "report_id": 1,
  "red": 255,
  "green": 128,
  "blue": 0
}
```
(Note: The actual returned bytes from the firmware might be inverted PWM values depending on implementation.)
```

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

### Get Current LED Color State via HID Feature Report (C)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

This code retrieves the current RGB color state of the BlinkStick device using a HID GET_REPORT request with report ID 1. The host receives a 4-byte buffer containing the report ID and the Red, Green, and Blue values. The firmware returns inverted PWM values from its OCR registers.

```c
// HID Feature Report 1: Current device colors (4 bytes)
// [Report ID (1)] [Red] [Green] [Blue]

// Host-side request using hidapi or libusb HID
unsigned char buffer[4];
int result = hid_get_feature_report(device, buffer, sizeof(buffer));

// buffer[0] = 1 (report ID)
// buffer[1] = red value (0-255)
// buffer[2] = green value (0-255)
// buffer[3] = blue value (0-255)

if (result > 0) {
    printf("Current color - R:%d G:%d B:%d\n",
           buffer[1], buffer[2], buffer[3]);
}

// Example: Reading color when red=255, green=128, blue=0
// Returns: [0x01, 0xFF, 0x80, 0x00]

// Firmware implementation (main.cpp:216-223)
// Returns inverted PWM values from OCR registers
```

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

### Write Device Name to EEPROM (C)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

Stores a custom 32-byte device name to the EEPROM using HID report ID 2. The data is written to EEPROM starting at offset 32 and persists across power cycles. This function should be used cautiously due to limited EEPROM write cycles.

```c
// HID Feature Report 2: Set device name (33 bytes)
unsigned char name_data[33];
name_data[0] = 2;  // Report ID

// Set device name (max 32 chars, null-padded)
const char *new_name = "MyBlinkStick";
memset(&name_data[1], 0, 32);  // Zero-fill
strncpy((char *)&name_data[1], new_name, 32);

int result = hid_send_feature_report(device, name_data, sizeof(name_data));

if (result > 0) {
    printf("Device name updated successfully\n");
}

// The firmware writes to EEPROM starting at offset 32
// Data persists across power cycles
// (main.cpp:255-261, 113-151)

// Note: EEPROM has limited write cycles (~100,000)
// Avoid frequent updates in production

```

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

### Build, Flash, and Deploy Blinkstick Firmware (Makefile)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

This Makefile provides commands for building the firmware hex file, flashing it to the ATTiny85 device, programming fuses, and a comprehensive 'deploy' target that combines flashing with serial number updates and default EEPROM writing. It uses AVR-GCC and avrdude utilities.

```makefile
# Build configuration (Makefile:11-21)
DEVICE  = attiny85
F_CPU   = 16500000
FUSE_L  = 0xe1  # External crystal, no div8
FUSE_H  = 0xdd  # Brown-out at 2.7V, preserve EEPROM

# Build firmware hex file
make hex

# Output:
# avr-gcc -Wall -Os -DF_CPU=16500000 -mmcu=attiny85 -c main.cpp -o main.o
# avr-gcc -Wall -Os -DF_CPU=16500000 -mmcu=attiny85 -c usbdrv/usbdrv.c -o usbdrv/usbdrv.o
# ...
# avr-objcopy -j .text -j .data -O ihex main.elf main.hex
# AVR Memory Usage:
# Program:    6234 bytes (76.0% Full)
# Data:         78 bytes (15.2% Full)

# Flash firmware to device
make flash
# avrdude -c usbtiny -P usb -p attiny85 -U flash:w:main.hex:i

# Program fuses (only needed once)
make fuse
# avrdude -c usbtiny -P usb -p attiny85 -U hfuse:w:0xdd:m -U lfuse:w:0xe1:m

# Complete deployment: flash + increment serial + write defaults
make deploy
```

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

### Device Initialization Sequence (C)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

Initializes the BlinkStick firmware by setting up the watchdog timer, serial number, USB stack, configuring LED pins, initializing PWM, and entering the main event loop. It handles USB re-enumeration and includes a delay for proper device detection.

```c
// main.cpp:337-372
int main(void) {
    uchar i;

    // Enable watchdog timer (1 second timeout)
    wdt_enable(WDTO_1S);

    // Load serial number from EEPROM
    SetSerial();

    // Initialize USB stack
    usbInit();

    // Force USB re-enumeration
    usbDeviceDisconnect();
    i = 0;
    while(--i) {  // Delay ~250ms
        wdt_reset();
        _delay_ms(1);
    }
    usbDeviceConnect();

    // Configure LED pins as outputs
    LED_PORT_DDR |= _BV(R_BIT);
    LED_PORT_DDR |= _BV(G_BIT);
    LED_PORT_DDR |= _BV(B_BIT);

    // Initialize PWM timers
    pwmInit();

    // Enable interrupts
    sei();

    // Main event loop
    for(;;) {
        wdt_reset();      // Pet the watchdog
        usbPoll();        // Process USB events
    }

    return 0;
}

// The device appears on the USB bus as:
// VID:PID - defined in usbconfig.h
// Class: HID (Human Interface Device)
// Subclass: None
// Protocol: None
// Manufacturer: Defined in usbconfig.h
// Product: "BlinkStick" (or custom from EEPROM)
// Serial: Read from EEPROM bytes 1-12

```

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

### EEPROM Memory Layout and Programming Steps (C & Shell)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

This section outlines the EEPROM memory map for the Blinkstick, detailing the layout from byte 0 to 511, including space for calibration, serial number, device name, and configuration. It also provides a sequence of commands using Ruby and 'make' targets to generate the EEPROM hex file, flash it to the device, and then dump and parse the EEPROM content for verification.

```c
// EEPROM Memory Map (512 bytes total)
// Byte 0:      OSCCAL calibration value (written by firmware)
// Bytes 1-12:  Serial number "BSXXXXXX-1.0" (12 chars)
// Bytes 13-31: Reserved (unused, zero-filled)
// Bytes 32-63: Device name (32 bytes, Report ID 2)
// Bytes 64-95: Extended config (32 bytes, Report ID 3)
// Bytes 96-511: Available for future use

// Default EEPROM initialization
// 1. Generate eeprom.hex with serial number
ruby increment.rb

// 2. Flash default EEPROM to device
make defaults
// avrdude -c usbtiny -P usb -p attiny85 -U eeprom:w:eeprom.hex:i

// 3. Read back EEPROM for verification
make dump
// avrdude -c usbtiny -P usb -p attiny85 -U eeprom:r:blinkstick-eeprom.hex:i

// 4. Parse dumped EEPROM
ruby -e "data = File.read('blinkstick-eeprom.hex'); \
         puts data.scan(/:..(.{24})/).flatten.join.scan(/../).map{|b| b.to_i(16).chr}.join"
// Output: BS000042-1.0 [device name] [config data]
```

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

### PWM Initialization and LED Pin Mapping (C)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

Initializes three PWM channels on an ATTiny85 microcontroller for RGB LED control using Timer0 and Timer1. It maps Red, Green, and Blue LEDs to specific microcontroller pins and configures the timers for PWM output. Note that the brightness values are inverted (0=full brightness, 255=off).

```c
// Hardware pin definitions (main.cpp:10-14)
#define LED_PORT_DDR        DDRB
#define LED_PORT_OUTPUT     PORTB
#define R_BIT            1  // Red on PB1 (OC0B)
#define G_BIT            0  // Green on PB0 (OC0A)
#define B_BIT            4  // Blue on PB4 (OC1B)

// PWM initialization function (main.cpp:317-334)
void pwmInit(void) {
    // Enable PWM on Timer1 channel B
    GTCCR |= _BV(PWM1B) | _BV(COM1B1);

    // Enable Fast PWM mode on Timer0 for both channels
    TCCR0A |= _BV(WGM00) | _BV(WGM01) | _BV(COM0A1) | _BV(COM0B1);

    // Start timers with no prescaling
    TCCR1 |= _BV(CS10);
    TCCR0B |= _BV(CS00);

    // Initialize all channels to off (255 = 0% duty for inverted)
    OCR0A = 255;  // Green channel
    OCR0B = 255;  // Red channel
    OCR1B = 255;  // Blue channel
}

// Wire an RGB LED (common anode) to:
// - PB0 (pin 5) -> Green LED cathode (330Ω resistor)
// - PB1 (pin 6) -> Red LED cathode (330Ω resistor)
// - PB4 (pin 3) -> Blue LED cathode (330Ω resistor)
// - VCC (pin 8) -> Common anode

// Values are inverted: 0=full brightness, 255=off

```

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

### USB Configuration and Oscillator Calibration (C)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

Configures the V-USB stack for a microcontroller and performs automatic oscillator calibration to ensure precise timing for USB communication. This calibration uses a binary and neighborhood search to find the optimal OSCCAL value, which is stored in EEPROM byte 0.

```c
// USB configuration in usbconfig.h
#define USB_CFG_IOPORTNAME      B
#define USB_CFG_DMINUS_BIT      3  // D- on PB3
#define USB_CFG_DPLUS_BIT       2  // D+ on PB2 (must be INT0)
#define F_CPU                   16500000  // 16.5 MHz internal RC

// Oscillator calibration during USB reset (main.cpp:277-314)
static void calibrateOscillator(void) {
    uchar step = 128;
    uchar trialValue = 0;
    int targetValue = (unsigned)(1499 * (double)F_CPU / 1.05e7 + 0.5);

    // Binary search for optimal OSCCAL value
    do {
        OSCCAL = trialValue + step;
        int x = usbMeasureFrameLength();
        if (x < targetValue)
            trialValue += step;
        step >>= 1;
    } while(step > 0);

    // Neighborhood search for best value
    uchar optimumValue = trialValue;
    int optimumDev = x;
    for (OSCCAL = trialValue - 1; OSCCAL <= trialValue + 1; OSCCAL++) {
        x = usbMeasureFrameLength() - targetValue;
        if (abs(x) < optimumDev) {
            optimumDev = abs(x);
            optimumValue = OSCCAL;
        }
    }
    OSCCAL = optimumValue;
}

// Calibrated value is stored in EEPROM byte 0
// Ensures reliable USB communication at 16.5 MHz

```

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

### Configure USB Endpoint Properties (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Introduces USB_CFG_DESCR_PROPS_* defines in usbconfig.h for configuring endpoint descriptor properties. This allows for more detailed control over how each USB endpoint is described and configured.

```c
  - Introduced USB_CFG_DESCR_PROPS_* in usbconfig.h to configure how each
```

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

### HID Implementation Preparation (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Indicates that the USB driver has been prepared for Human Interface Device (HID) implementations. This involves setting up the necessary structures and functionalities to support HID devices.

```c
  - Prepared for HID implementations.
```

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

### Generate Serial Number and EEPROM Hex File (Ruby)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

This Ruby script, 'increment.rb', generates a new serial number by incrementing a counter stored in 'serial.txt'. It formats the serial number as 'BSXXXXXX-1.0', converts it to ASCII byte values, and creates an 'eeprom.hex' file in Intel HEX format, padded to 512 bytes. It then updates the counter in 'serial.txt'.

```ruby
#!/usr/bin/ruby -w
# increment.rb - Generate next serial number and EEPROM hex file

require "wo_oo/util/hex"
require "./intel_hex.rb"

# Read current serial number
file = File.new("serial.txt", "r")
line = file.gets
file.close

# Increment serial number
serial_number = line.to_i + 1

# Format: BSXXXXXX-1.0 (BS000001-1.0, BS000002-1.0, etc.)
serial_string = "BS%06d-1.0" % serial_number

data = []
data.push 0  # Byte 0: reserved for OSCCAL value

# Bytes 1-12: Serial number ASCII characters
serial_string.split("").each do |c|
  data.push c.ord
end

# Pad to 512 bytes
while data.length < 512 do
  data.push 0
end

# Write Intel HEX format file
HexFile.write("eeprom.hex", data)

# Save incremented counter
file = File.new("serial.txt", "w")
file.puts serial_number
file.close

# Usage: ruby increment.rb
# Output: eeprom.hex with new serial number
# Then: make defaults (writes eeprom.hex to device)
```

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

### Set LED Color via HID Report

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

Configure the LED's color by sending a HID SET_REPORT request. This method allows setting all three RGB channels simultaneously using report ID 1.

```APIDOC
## SET LED COLOR VIA HID REPORT

### Description
Sets the RGB color of the BlinkStick LED by sending a HID SET_REPORT request with report ID 1. This command updates all three color channels at once.

### Method
HID SET_REPORT or USB Control Transfer

### Endpoint
N/A (handled via HID or Control Transfer API)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **report_id** (byte) - Must be 1.
- **red** (byte) - Red channel value (0-255).
- **green** (byte) - Green channel value (0-255).
- **blue** (byte) - Blue channel value (0-255).

### Request Example
```c
// HID Feature Report 1: Set device colors (4 bytes)
// [Report ID (1)] [Red] [Green] [Blue]

unsigned char color_data[4] = {
    0x01,  // Report ID
    255,   // Red channel (0-255)
    64,    // Green channel (0-255)
    192    // Blue channel (0-255)
};

// Using hidapi:
// int result = hid_send_feature_report(device, color_data, sizeof(color_data));

// Using libusb control transfer:
// usb_control_msg(
//     dev_handle,
//     USB_TYPE_CLASS | USB_RECIP_INTERFACE | USB_ENDPOINT_OUT,
//     USBRQ_HID_SET_REPORT, // Standard HID SET_REPORT request
//     (3 << 8) | 1,  // Report Type = Feature (3), Report ID = 1
//     0,             // Interface number
//     color_data,
//     4,             // Length of data
//     5000           // Timeout ms
// );
```

### Response
#### Success Response (200)
Acknowledgement of the HID report transmission.

#### Response Example
None (typically no data returned, success indicated by lack of error.
```

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

### Set Individual RGB Color Channels (Vendor Request)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

This section describes how to set individual Red, Green, or Blue color channels directly using custom USB vendor requests. These requests bypass HID reports for fine-grained control.

```APIDOC
## SET INDIVIDUAL RGB COLOR CHANNELS (VENDOR REQUEST)

### Description
Control individual Red, Green, or Blue LED channels using custom USB vendor requests. These are processed directly by the firmware's setup handler.

### Method
Control Transfer (USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_IN)

### Endpoint
N/A (handled by control transfer)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// Define request codes (from requests.h)
#define CUSTOM_RQ_SET_RED    3
#define CUSTOM_RQ_SET_GREEN  4
#define CUSTOM_RQ_SET_BLUE   5

// Example: Set red channel to brightness 128
usb_control_msg(
    dev_handle,
    USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_IN,
    CUSTOM_RQ_SET_RED,    // bRequest = 3
    128,                   // wValue = brightness (0-255)
    0,                     // wIndex
    NULL,                  // no data phase
    0,                     // length
    5000                   // timeout ms
);

// Example: Set green and blue channels
usb_control_msg(dev_handle, USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_IN,
    CUSTOM_RQ_SET_GREEN, 200, 0, NULL, 0, 5000);
usb_control_msg(dev_handle, USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_IN,
    CUSTOM_RQ_SET_BLUE, 50, 0, NULL, 0, 5000);
```

### Response
#### Success Response (200)
Control transfer acknowledgement.

#### Response Example
None (typically no data returned for these requests)
```

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

### USB Function Interface Changes (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Describes modifications to the application interface for USB functions. Previously, specific functions were used; now, a more generalized approach with usbFunctionSetup(), usbFunctionRead(), and usbFunctionWrite() is adopted, with options to enable only the necessary functions.

```c
  - Changed interface to application: Use usbFunctionSetup(), usbFunctionRead() and usbFunctionWrite() now. Added configuration options to choose which of these functions to compile in.
```

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

### USB Driver Readme File (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Includes a Readme.txt file in the usbdrv directory to clarify administrative issues related to the USB driver. This file serves as a central point for understanding usage and management guidelines.

```c
  - Added Readme.txt to the usbdrv directory which clarifies administrative
    issues.
```

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

### Read and Report Blinkstick Serial Number (C)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

This C code snippet demonstrates how to read a 12-character serial number from EEPROM and configure it to be reported via USB descriptors. It defines the serial number format and includes functions for setting the serial number descriptor and handling USB descriptor requests.

```c
// Serial number format: "BSXXXXXX-1.0" (12 characters)
// Stored in EEPROM bytes 1-12

// Reading serial number from EEPROM (main.cpp:172-183)
#define SERIAL_NUMBER_LENGTH 12
static int serialNumberDescriptor[SERIAL_NUMBER_LENGTH + 1];

static void SetSerial(void) {
    serialNumberDescriptor[0] = USB_STRING_DESCRIPTOR_HEADER(SERIAL_NUMBER_LENGTH);

    uchar serialNumber[SERIAL_NUMBER_LENGTH];
    eeprom_read_block(serialNumber, (uchar *)0 + 1, SERIAL_NUMBER_LENGTH);

    for (int i = 0; i < SERIAL_NUMBER_LENGTH; i++) {
        serialNumberDescriptor[i + 1] = serialNumber[i];
    }
}

// USB descriptor callback (main.cpp:158-168)
uchar usbFunctionDescriptor(usbRequest_t *rq) {
    if (rq->wValue.bytes[1] == USBDESCR_STRING &&
        rq->wValue.bytes[0] == 3) {
        usbMsgPtr = (uchar*)serialNumberDescriptor;
        return sizeof(serialNumberDescriptor);
    }
    return 0;
}

// Example: Read serial from Linux
// cat /sys/bus/usb/devices/*/serial | grep "BS"
// Output: BS000001-1.0
```

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

### USB Receive Buffer Page Alignment (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Allows the USB receive buffer (usbRxBuf) to be located on any memory page, provided the buffer itself does not cross 256-byte page boundaries. This offers more flexibility in memory allocation.

```c
  - Allow address of usbRxBuf on any memory page as long as the buffer
    does not cross 256 byte page boundaries.
```

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

### Read Device Name from EEPROM via HID Feature Report (C)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

This C code snippet demonstrates how to read the 32-byte device name stored in the BlinkStick's EEPROM using HID report ID 2. The host sends a GET_REPORT request, and the firmware responds with a buffer containing the report ID followed by the device name. The name is null-padded if shorter than 32 characters.

```c
// HID Feature Report 2: Device name (33 bytes)
// [Report ID (2)] [32 bytes of name data]

unsigned char name_buffer[33];
name_buffer[0] = 2;  // Report ID

int result = hid_get_feature_report(device, name_buffer, sizeof(name_buffer));

if (result > 0) {
    // Name starts at byte 1, up to 32 characters
    char device_name[33];
    memcpy(device_name, &name_buffer[1], 32);
    device_name[32] = '\0';
    printf("Device name: %s\n", device_name);
}

// Example output: "BlinkStick"
// Remaining bytes are null-padded

// Firmware reads from EEPROM offset 32
// (main.cpp:226-234, 81-107)
```

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

### USB New Defines for Constants (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Introduces new defines for USB constants within the driver. This improves code readability and maintainability by using named constants instead of raw numerical values.

```c
  - New defines for USB constants.
```

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

### USB Driver Documentation Updates (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Updates documentation within usbdrv.h and usbconfig-prototype.h to reflect new features and API changes. This ensures that the documentation remains accurate and useful for developers using the USB driver.

```c
  - Documentation updates.
  - Updated docs in usbdrv.h to reflect changed API in usbFunctionWrite().
  - Updated documentation in usbdrv.h and usbconfig-prototype.h to reflect the
    new features.
```

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

### Set Individual RGB Color Channels via USB Vendor Request (C)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

This snippet demonstrates how to set individual Red, Green, or Blue color channels using custom USB vendor requests. It involves sending control messages with specific request codes and values to the device. The firmware processes these requests to adjust the PWM output for each color channel. Note that the firmware inverts values for common anode LEDs.

```c
// requests.h definitions
#define CUSTOM_RQ_SET_RED    3
#define CUSTOM_RQ_SET_GREEN  4
#define CUSTOM_RQ_SET_BLUE   5

// Host-side control transfer to set red channel to brightness 128
// Using libusb or similar USB library:
usb_control_msg(
    dev_handle,
    USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_IN,
    CUSTOM_RQ_SET_RED,    // bRequest = 3
    128,                   // wValue = brightness (0-255)
    0,                     // wIndex
    NULL,                  // no data phase
    0,                     // length
    5000                   // timeout ms
);

// Set all three channels
usb_control_msg(dev_handle, USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_IN,
    CUSTOM_RQ_SET_GREEN, 200, 0, NULL, 0, 5000);
usb_control_msg(dev_handle, USB_TYPE_VENDOR | USB_RECIP_DEVICE | USB_ENDPOINT_IN,
    CUSTOM_RQ_SET_BLUE, 50, 0, NULL, 0, 5000);

// Firmware handling (main.cpp:198-210)
// Values are inverted (255 - value) for common anode LEDs
// OCR registers control PWM duty cycle on timer outputs
```

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

### IAR C Compiler Compatibility (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Introduces changes to ensure compatibility with the IAR C compiler. This includes support for the tiny memory model, more devices, and preventing the inclusion of <avr/io.h> when compiling with IAR. Warnings are generated using static variables instead of '#warning' directives.

```c
  - Added Oleg Semyonov's changes for IAR-cc compatibility.
  - Improved IAR C support: tiny memory model, more devices
  - Removed "#warning" directives because IAR does not understand them. Use
    unused static variables instead to generate a warning.
  - Do not include <avr/io.h> when compiling with IAR.
```

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

### USB Endpoint Provisioning (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Adds support for additional interrupt endpoints, including one interrupt-in endpoint (endpoint 3) and one interrupt-out endpoint (endpoint 1). This expands the device's capability for interrupt-driven data transfer.

```c
  - Added provision for one more interrupt-in endpoint (endpoint 3).
  - Added provision for one interrupt-out endpoint (endpoint 1).
```

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

### USB Endpoint 3 Provisioning (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Adds support for an additional interrupt-in endpoint, specifically endpoint 3. This allows for more data transfer channels using the interrupt-in mechanism.

```c
  - Added provision for one more interrupt-in endpoint (endpoint 3).
```

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

### Read Extended Configuration Data from EEPROM (C)

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

Retrieves 32 bytes of extended configuration data from EEPROM using HID report ID 3. The firmware reads this data from EEPROM offset 64. This data can be used to store custom application data or preferences.

```c
// HID Feature Report 3: Extended data (33 bytes)
// [Report ID (3)] [32 bytes of config data]

unsigned char config_buffer[33];
config_buffer[0] = 3;  // Report ID

int result = hid_get_feature_report(device, config_buffer, sizeof(config_buffer));

if (result > 0) {
    // Configuration data starts at byte 1
    printf("Extended config data:\n");
    for (int i = 1; i < 33; i++) {
        printf("%02X ", config_buffer[i]);
        if (i % 16 == 0) printf("\n");
    }
}

// Firmware reads from EEPROM offset 64
// Can store custom application data, preferences, etc.
// (main.cpp:236-244)

```

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

### USB Interrupt Buffer Query Macro (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Introduces the usbInterruptIsReady() macro, which allows querying the state of the interrupt buffer. This helps in determining if the interrupt buffer is ready to receive or send data.

```c
  - New macro usbInterruptIsReady() to query interrupt buffer state.
```

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

### USB Endpoint 1 Provisioning (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Adds support for an interrupt-out endpoint, specifically endpoint 1. This enables sending data from the host to the device using the interrupt-out transfer type.

```c
  - Added provision for one interrupt-out endpoint (endpoint 1).
```

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

### USB Custom Configuration Descriptor (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Adds provision for a custom configuration descriptor. This allows developers to define a unique configuration descriptor tailored to their specific device needs, overriding the default.

```c
  - Added provision for custom configuration descriptor.
```

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

### USB Data Packet Handling (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Ensures that the data token sent as an ACK for an OUT transfer is always zero-sized. This corrects a bug where the host might report an error after an OUT transfer, even if data was received correctly.

```c
  - Ensure that the data token which is sent as an ack to an OUT transfer is
    always zero sized. This fixes a bug where the host reports an error after
    sending an out transfer to the device, although all data arrived at the
    device.
```

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

### Configure USB Port Name (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Updates the configuration mechanism for USB I/O ports, replacing USB_CFG_IOPORT with USB_CFG_IOPORTNAME. This change simplifies the way the port name is specified, constructing the variable name from a single port letter.

```c
  - Use USB_CFG_IOPORTNAME instead of USB_CFG_IOPORT. We now construct the
    variable name from the single port letter instead of computing the address
    of related ports from the output-port address.
```

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

### USB Polling Optimization (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Rearranges the tests within the usbPoll() function to save instructions in the common case where no actions are pending. This optimization improves the efficiency of the main polling loop.

```c
  - Rearranged tests in usbPoll() to save a couple of instructions in the most
    likely case that no actions are pending.
```

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

### USB Request Structure (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Provides a structure definition for usbRequest_t, which is used to represent USB requests. This structure facilitates the management and parsing of USB request data.

```c
  - Provide structure for usbRequest_t.
```

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

### Read Device Name from EEPROM

Source: https://context7.com/arvydas/blinkstick-firmware/llms.txt

Retrieve the custom 32-byte device name stored in the device's EEPROM. This is accessed via HID report ID 2.

```APIDOC
## READ DEVICE NAME FROM EEPROM

### Description
Fetches the 32-byte device name stored in the BlinkStick's EEPROM using a HID GET_REPORT request with report ID 2.

### Method
HID GET_REPORT

### Endpoint
N/A (handled via HID API)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// HID Feature Report 2: Device name (33 bytes expected response)
// [Report ID (2)] [32 bytes of name data]

unsigned char name_buffer[33];
name_buffer[0] = 2;  // Set report ID to 2

// Using hidapi library:
int result = hid_get_feature_report(device, name_buffer, sizeof(name_buffer));

if (result > 0) {
    // The actual name data starts from the second byte (index 1)
    char device_name[33];
    memcpy(device_name, &name_buffer[1], 32);
    device_name[32] = '\0'; // Null-terminate the string
    printf("Device name: %s\n", device_name);
}
```

### Response
#### Success Response (200)
- **report_id** (byte) - Always 2 for this report.
- **device_name** (string) - The 32-byte device name, null-padded if shorter.

#### Response Example
```json
{
  "report_id": 2,
  "device_name": "BlinkStick"
}
```
```

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

### Merge RX Token Variable (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Merges the receive endpoint number into the global usbRxToken variable. This consolidates endpoint information, potentially simplifying state management within the driver.

```c
  - Merged (optional) receive endpoint number into global usbRxToken variable.
```

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

### Configure USB Port Pin Usage (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Allows flexible configuration of the port bits used for USB D+ and D- lines. This change enables the use of any two port bits for USB communication, increasing hardware adaptability.

```c
  - Allow ANY two port bits for D+ and D-.
```

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

### USB Driver Debugging Warning (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Includes a compiler warning when the USB driver is compiled with debugging enabled. This serves as a reminder that debug builds may have performance implications.

```c
  - Give a compiler warning when compiling with debugging turned on.
```

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

### Handle USB Device Connection/Disconnection (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Introduces optional functions, usbDeviceConnect() and usbDeviceDisconnect(), to manage the USB device's connection state. This provides explicit control over when the device connects to or disconnects from the USB bus.

```c
  - Added new (optional) functions usbDeviceConnect() and usbDeviceDisconnect()
```

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

### USB Driver Optimization (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Includes various minor optimizations to the USB driver code. These optimizations aim to improve performance and reduce resource usage, such as recommending the '-Os' compiler option for best results.

```c
  - Various minor optimizations.
  - Code optimization in debugging module.
  - Minor optimizations, we now recommend compiler option "-Os" for best
    results.
```

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

### Implement USB Interrupt-In Endpoint 1 (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Details the implementation of the first interrupt-in endpoint for the USB driver. This change affects how data is received from the host.

```c
  - Implemented endpoint 1 as interrupt-in endpoint.
```

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

### USB Driver Standards Compliance (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Enhances the USB driver's adherence to USB standards by introducing a 'configured state' and a 'HALT' state for interrupt endpoints. The driver now passes the 'USB Command Verifier' test from usb.org.

```c
  - Added "configured state" to become more standards compliant.
  - Added "HALT" state for interrupt endpoint.
  - Driver passes the "USB Command Verifier" test from usb.org now.
```

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

### USB Enumeration Delay Handling (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Moves the handling of the delay required after a SET ADDRESS request from usbPoll() to the interrupt routine. This change ensures the delay does not exceed 2ms and improves enumeration efficiency by avoiding aggressive polling.

```c
  - We need a delay between the SET ADDRESS request until the new address
    becomes active. This delay was handled in usbPoll() until now. Since the
    spec says that the delay must not exceed 2ms, previous versions required
    aggressive polling during the enumeration phase. We have now moved the
    handling of the delay into the interrupt routine.
```

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

### USB Driver Version Number (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Adds a version number to the usbdrv.h header file. This allows developers to easily identify the version of the USB driver being used.

```c
  - Added a version number to usbdrv.h
```

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

### Configure Serial Number (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Makes the 'serial number' a configurable option within the USB driver. This allows for customization of the device's serial number, which can be important for device identification.

```c
  - Made "serial number" a configuration option.
```

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

### USB Flow Control Macros (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Adds flow control macros for USB operations. These macros help manage the data flow during USB communication, ensuring reliable data transfer.

```c
  - Added flowcontrol macros for USB.
```

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

### AVR Assembler Receive Data Inversion (Assembly)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Changes the assembler module responsible for receiving data to deliver it in a non-inverted format. This simplifies data handling in the C code by providing consistently formatted input.

```assembly
  - Assembler module delivers receive data non-inverted now.
```

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

### AVR Device Compatibility (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Addresses compatibility issues with specific AVR devices, including the ATMega8 and Mega88. Register and bit names have been made compatible with a wider range of AVR devices.

```c
  - Fixed compatibility with ATMega8 device.
  - Better device compatibility: works with Mega88 now.
  - Made register and bit names compatible with more AVR devices.
```

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

### USB Interrupt Transfer Data Size Limit (C)

Source: https://github.com/arvydas/blinkstick-firmware/blob/master/usbdrv/Changelog.txt

Increases the maximum data size limit for interrupt transfers to 8 bytes. This accommodates larger data payloads for interrupt-driven communication.

```c
  - Increased data size limit for interrupt transfers to 8 bytes.
```

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