ปลั๊กอินคืออะไร?

SignalRGB ใช้ปลั๊กอิน USB แบบกำหนดเองที่เขียนด้วย JavaScript เพื่อรองรับอุปกรณ์ RGB จากผู้ผลิตภายนอก หากคุณมีอุปกรณ์ที่ยังไม่ได้รับการรองรับ คุณสามารถเขียนปลั๊กอินของคุณเองได้ หากคุณมี Arduino หรือไมโครคอนโทรลเลอร์แบบโอเพนซอร์สอื่น ๆ คุณก็สามารถสร้างปลั๊กอินให้ SignalRGB สื่อสารกับอุปกรณ์นั้นเพื่อสร้างโซลูชัน RGB แบบ DIY ได้อย่างเต็มรูปแบบ

ปลั๊กอินที่เราเผยแพร่อยู่ในปัจจุบันเป็นซอร์สโค้ดที่อ่านได้ และมีให้ใช้งานในคลังปลั๊กอิน SignalRGB สาธารณะ หากคุณสร้างสิ่งที่ผู้อื่นสามารถใช้ได้ คุณสามารถส่ง pull request หรือติดต่อฝ่ายสนับสนุนอย่างเป็นทางการของเราได้เลย!

---

ปลั๊กอินทำงานอย่างไร

ปลั๊กอินคือไฟล์ JavaScript ไฟล์เดียวที่ SignalRGB โหลดสำหรับอุปกรณ์ USB ที่เฉพาะเจาะจง โดยทำหน้าที่สองอย่าง:

1. อธิบายอุปกรณ์ — export ต่าง ๆ ที่บอก SignalRGB เกี่ยวกับชื่อ ID เลย์เอาต์ LED และโปรโตคอลการสื่อสารของอุปกรณ์
2. ขับเคลื่อนอุปกรณ์ — ฟังก์ชันวงจรชีวิตที่ SignalRGB เรียกเพื่อเริ่มต้นอุปกรณ์ ส่งสีในทุกเฟรม และเก็บกวาดเมื่อออกจากโปรแกรม

---

โครงสร้างปลั๊กอิน

ปลั๊กอินทุกตัวมีรูปแบบพื้นฐานเหมือนกัน:

// ── Device identity ──────────────────────────────────────
export function Name()      { return "My Device"; }
export function Publisher() { return "Your Name"; }
export function VendorId()  { return 0x1234; }
export function ProductId() { return 0x5678; }
export function Type()      { return "hid"; }

// ── Canvas size and LED layout ────────────────────────────
export function Size()      { return [7, 3]; }
export function LedNames()  { return ["Logo", "Left", "Right"]; }
export function LedPositions() { return [[3,1], [0,1], [6,1]]; }

// ── Lifecycle ─────────────────────────────────────────────
export function Initialize() {
    // Called once when the device connects or streaming is enabled.
    // Send any initialization packets the device needs here.
    SendInitPacket();
}

export function Render() {
    // Called every frame (~30ms by default).
    // Read colors from the canvas and send them to the device.
    SendColors();
}

export function Shutdown() {
    // Called when SignalRGB exits or streaming is disabled.
    // Return the device to hardware mode here if needed.
    SetHardwareControl();
}

---

วงจรชีวิต

Initialize

ถูกเรียกหนึ่งครั้งเมื่ออุปกรณ์เชื่อมต่อหรือเชื่อมต่อใหม่ และทุกครั้งที่เปิดสวิตช์สตรีมมิงบนหน้าการกำหนดค่าของอุปกรณ์ ใช้สำหรับงานเริ่มต้นต่าง ๆ เช่น การสลับอุปกรณ์เข้าสู่โหมดควบคุมด้วยซอฟต์แวร์ การส่งแฮนด์เชกของเฟิร์มแวร์ การอ่านการกำหนดค่าที่บันทึกไว้ เป็นต้น

หากมีโปรเซสที่ขัดแย้งทำงานอยู่ การเริ่มต้นจะรอจนกว่าโปรเซสเหล่านั้นจะปิดลงหรือผู้ใช้ข้ามการตรวจสอบ

Render

ลูปการเรนเดอร์คือหัวใจหลักของปลั๊กอิน SignalRGB จะเรียก Render() ทุกเฟรม ลำดับการทำงานในแต่ละเฟรมคือ:

1. การตั้งค่าของผู้ใช้ถูกอัปเดต
2. สีถูกดึงจากแคนวาสเข้าสู่บัฟเฟอร์พิกเซลของอุปกรณ์
3. คอลแบ็ก on*Changed ต่าง ๆ ทำงาน (ตามลำดับที่เกิดการเปลี่ยนแปลง)
4. Render() ถูกเรียก

ภายใน Render() คุณจะเรียก device.color(x, y) เพื่ออ่านสีพิกเซลแล้วส่งไปยังฮาร์ดแวร์ ช่วงเวลาระหว่างเฟรมเริ่มต้นคือ 30ms

Shutdown

ถูกเรียกเมื่อ SignalRGB ปิดตัวลงอย่างถูกต้องหรือเมื่อปิดสวิตช์สตรีมมิง หากอุปกรณ์ของคุณมีโหมดไฟแบบฮาร์ดแวร์ ให้คืนค่าโหมดนั้นที่นี่ เพื่อให้ LED ของผู้ใช้ไม่ดับเมื่อ SignalRGB ไม่ได้ทำงาน

คอลแบ็ก on*Changed

ตัวควบคุมที่ผู้ใช้มองเห็น (ดู ControllableParameters) แต่ละตัวสามารถมีคอลแบ็กที่คู่กัน ซึ่งจะทำงานก่อน Render() ทุกครั้งที่ผู้ใช้เปลี่ยนการตั้งค่านั้น ให้ตั้งชื่อฟังก์ชันว่า on[propertyName]Changed() — โดยคำนึงถึงตัวพิมพ์เล็กใหญ่

// ControllableParameters entry:
{ "property": "dpi1", "label": "DPI", "type": "number", "min": "200", "max": "18000", "default": "800" }

// Matching callback:
export function ondpi1Changed() {
    setDpi(dpi1);
}

คอลแบ็กในตัว onBrightnessChanged() จะทำงานเมื่อมีการเลื่อนแถบเลื่อนความสว่างหลักของอุปกรณ์

---

การกำหนดอุปกรณ์

export เหล่านี้บอก SignalRGB ทุกสิ่งที่จำเป็นต้องรู้เกี่ยวกับอุปกรณ์ก่อนที่จะเชื่อมต่อ

Name และ Publisher

แสดงใน UI ของ SignalRGB

export function Name()      { return "Corsair K70 RGB"; }
export function Publisher() { return "YourName"; }

VendorId และ ProductId

ID ของ USB ที่ SignalRGB ใช้ค้นหาอุปกรณ์ในระบบ ต้องเป็นค่าฐานสิบหกที่ตรงกันทุกประการ หากปลั๊กอินของคุณไม่ปรากฏ สาเหตุที่เป็นไปได้มากที่สุดคือ ID ไม่ตรงกัน

export function VendorId()  { return 0x1B1C; }
export function ProductId() { return 0x1B49; }

Type

กำหนดโปรโตคอลการสื่อสาร USB ค่าเริ่มต้นคือ "hid" หากไม่ได้ export ดู การระบุประเภทอุปกรณ์ สำหรับรายการทั้งหมดและวิธีเลือก

export function Type() { return "hid"; }     // HID (most devices)
export function Type() { return "rawusb"; }  // Raw USB / libusb
export function Type() { return "hybrid"; }  // Both simultaneously
export function Type() { return "serial"; }  // COM port

Size, LedNames และ LedPositions

export ทั้งสามนี้ร่วมกันกำหนดว่าอุปกรณ์จะปรากฏบนแคนวาสอย่างไร

• Size() — กรอบขอบเขต [width, height] ของกริดพิกเซลของอุปกรณ์ device.color() สามารถสุ่มตัวอย่างพิกัดได้เฉพาะภายในกรอบนี้เท่านั้น
• LedNames() — อาร์เรย์ชื่อ LED ที่เรียงตามลำดับ ชื่อควรเป็นไปตามรายการชื่อปุ่มที่รองรับ เพื่อเปิดใช้เอฟเฟกต์การกดปุ่มและการระบายสี LED
• LedPositions() — อาร์เรย์ตำแหน่ง [x, y] ที่เรียงตามลำดับภายในกริด Size หนึ่งตำแหน่งต่อหนึ่ง LED ตรงกับลำดับของ LedNames

export function Size()         { return [7, 3]; }
export function LedNames()     { return ["Logo", "Left Side", "Right Side"]; }
export function LedPositions() { return [[3, 1], [0, 1], [6, 1]]; }

Validate

ควบคุมว่า SignalRGB จะเปิดเอนด์พอยต์ USB ใดบ้าง เอนด์พอยต์ทุกตัวที่ค้นพบจะถูกส่งไปยัง Validate() — ส่งคืน true เพื่อเปิด หรือ false เพื่อข้าม คุณสามารถเปิดหลายเอนด์พอยต์และสลับระหว่างกันขณะรันไทม์ได้ด้วย device.set_endpoint()

export function Validate(endpoint) {
    return endpoint.interface === 2 && endpoint.usage_page === 0xFF00;
}

ดู การเลือกเอนด์พอยต์ สำหรับวิธีหาค่าที่ถูกต้อง

ControllableParameters

ส่งคืนอาร์เรย์ของการตั้งค่าที่ผู้ใช้มองเห็นซึ่งปรากฏบนหน้าการกำหนดค่าของอุปกรณ์ ดู ตัวควบคุมสำหรับผู้ใช้ สำหรับสคีมาฉบับเต็ม

export function ControllableParameters() {
    return [
        { "property": "LightingMode", "label": "Lighting Mode", "type": "combobox",
          "values": ["Software", "Hardware"], "default": "Software" },
        { "property": "DPILevel", "label": "DPI", "type": "number",
          "min": "200", "max": "18000", "step": "50", "default": "800" }
    ];
}

ConflictingProcesses

รายชื่อไฟล์ exe ที่ขัดแย้งกับปลั๊กอินนี้ SignalRGB จะไม่เริ่มต้นอุปกรณ์ขณะที่มีโปรเซสใดในรายการนี้ทำงานอยู่ ชื่อต้องตรงกันทุกประการ

export function ConflictingProcesses() {
    return ["iCUE.exe", "CorsairHID.exe"];
}

ImageUrl

URL ของรูปภาพอุปกรณ์ที่แสดงใน UI ของ SignalRGB ขนาดมาตรฐานคือ 1024×1024 พร้อมพื้นที่แสดงผลจริง 920×920

export function ImageUrl() { return "https://..."; }

---

ขั้นตอนถัดไป

• เทมเพลตปลั๊กอิน — จุดเริ่มต้นที่พร้อมให้แก้ไข
• การเขียนและการอ่าน — การส่งข้อมูลไปยังอุปกรณ์
• การระบุประเภทอุปกรณ์ — การเลือกโปรโตคอลที่เหมาะสม
• การเลือกเอนด์พอยต์ — การค้นหาเอนด์พอยต์ USB ที่ถูกต้อง
• ตัวควบคุมสำหรับผู้ใช้ — การเพิ่มการตั้งค่าลงในหน้าการกำหนดค่าอุปกรณ์
• โมดูลและฟีเจอร์ — แบตเตอรี่ การจำลองคีย์บอร์ด/เมาส์ เครือข่าย และอื่น ๆ