Modules và tính năng

Các plugin có thể mở rộng khả năng của chúng vượt ra ngoài các lần đọc và ghi USB đơn giản với hai hệ thống: modules và tính năng. Hiểu sự khác biệt giữa chúng giúp bạn khám phá những gì có sẵn và sử dụng đúng cơ chế.

Modules vs. tính năng

	Modules	Tính năng
Sử dụng	import { x } from "@SignalRGB/name"	device.addFeature("name") trong Initialize()
Mục đích	Dịch vụ hỗ trợ (mạng, mã hóa, thông tin hệ thống)	Khả năng thiết bị (pin, tiêm nhập liệu)
Namespace	Tên module được xuất riêng	device.featureName.*
Instance	Một mỗi plugin	Có thể có nhiều

---

Modules có sẵn

Nhập chúng ở đầu tệp plugin của bạn.

Đường dẫn import	Mục đích
@SignalRGB/serial	Giao tiếp cổng Serial/COM
@SignalRGB/tcp	Giao tiếp TCP socket
@SignalRGB/udp	Giao tiếp UDP socket
@SignalRGB/base64	Mã hóa và giải mã Base64
@SignalRGB/performance	Lập hồ sơ hiệu suất và bộ đếm thời gian khung
@SignalRGB/appInfo	Thông tin phiên bản ứng dụng SignalRGB
@SignalRGB/systeminfo	Thông tin phần cứng hệ thống
@SignalRGB/permissions	Kiểm tra trạng thái quyền người dùng

Trong Giao tiếp nâng cao bạn sẽ tìm thấy các ví dụ sử dụng cho serial, tcp và udp.

---

Tính năng có sẵn

Gọi device.addFeature("name") trong export Initialize() của bạn. Tính năng tạo ra một đối tượng toàn cục với cùng tên với tính năng đó.

Tên tính năng	Namespace	Mục đích
"keyboard"	keyboard	Tiêm các lần nhấn phím hoặc chuyển tiếp sự kiện bàn phím đến macro SignalRGB
"mouse"	mouse	Tiêm nhập liệu chuột hoặc chuyển tiếp sự kiện chuột đến macro SignalRGB
"battery"	battery	Báo cáo mức và trạng thái pin cho các thiết bị không dây
"dtls"	dtls	UDP được mã hóa DTLS với xác thực PSK

---

Tính năng bàn phím

Dành cho các plugin đại diện cho thiết bị bàn phím. Cho phép tiêm các lần nhấn phím thực vào OS hoặc kích hoạt các sự kiện có thể kích hoạt macro SignalRGB.

export function Initialize() {
    device.addFeature("keyboard");
}

keyboard.sendHid(vkCode, options)

Gửi lần nhấn phím thô trực tiếp đến hệ điều hành qua keybd_event. Phím xuất hiện như nhập liệu thực đến tất cả các ứng dụng — hoàn toàn bỏ qua hệ thống macro.

Tham số	Kiểu	Mô tả	Ví dụ
vkCode	Number	Windows Virtual Key Code	0x41 (phím A)
options.released	Boolean (bắt buộc)	true cho Key-Up, false cho Key-Down	false

keyboard.sendHid(0x41, { released: false }); // Nhấn A
keyboard.sendHid(0x41, { released: true });  // Thả A

keyboard.sendEvent(eventData, eventType)

Chuyển tiếp sự kiện bàn phím qua hệ thống macro của SignalRGB. Các macro có trigger onKey có thể khớp các sự kiện này. Không tiêm lần nhấn phím thực — chỉ có macro SignalRGB mới thấy sự kiện này.

Hệ thống macro tự động bổ sung sự kiện với trạng thái modifier hiện tại (Ctrl, Shift, Alt, Win) từ bàn phím vật lý trước khi chuyển tiếp.

Tham số	Kiểu	Mô tả	Ví dụ
eventData	Object hoặc String	Dữ liệu sự kiện. Chỉ định key (tên chuỗi) và tùy chọn keyCode (số) để khớp khóa.	{ key: "A", keyCode: 0x41 }
eventType	String	Nhãn loại sự kiện	"KeyPress"

keyboard.sendEvent({ key: "A", keyCode: 0x41, released: false }, "KeyPress");

Các script macro nhận event.Sender (UID của plugin) và event.SenderType ("Device"), để chúng có thể phân biệt các sự kiện được kích hoạt bởi plugin với các lần nhấn phím phần cứng thực.

---

Tính năng chuột

Dành cho các plugin đại diện cho chuột hoặc thiết bị trỏ.

export function Initialize() {
    device.addFeature("mouse");
}

mouse.sendHid(buttonCode, options)

Gửi sự kiện chuột thô đến OS qua SendInput. Các chuyển động chuột (MOUSEEVENTF_MOVE, MOUSEEVENTF_ABSOLUTE) bị chặn vì lý do bảo mật.

Tham số	Kiểu	Mô tả
buttonCode	Number	Windows MOUSEEVENTF_* flag
options.XButton	Number	Bắt buộc cho các sự kiện nút X — 1 (X1) hoặc 2 (X2)
options.WheelDelta	Number	Bắt buộc cho các sự kiện bánh xe chuột — dương cuộn lên, âm cuộn xuống

Mã nút phổ biến:

Mã	Hằng số	Mô tả
0x0002	MOUSEEVENTF_LEFTDOWN	Nhấn nút trái
0x0004	MOUSEEVENTF_LEFTUP	Thả nút trái
0x0008	MOUSEEVENTF_RIGHTDOWN	Nhấn nút phải
0x0010	MOUSEEVENTF_RIGHTUP	Thả nút phải
0x0020	MOUSEEVENTF_MIDDLEDOWN	Nhấn nút giữa
0x0040	MOUSEEVENTF_MIDDLEUP	Thả nút giữa
0x0800	MOUSEEVENTF_WHEEL	Cuộn dọc
0x01000	MOUSEEVENTF_HWHEEL	Cuộn ngang
0x0080	MOUSEEVENTF_XDOWN	Nhấn nút X (yêu cầu tùy chọn XButton)
0x0100	MOUSEEVENTF_XUP	Thả nút X (yêu cầu tùy chọn XButton)

// Click trái
mouse.sendHid(0x0002, {});  // nhấn
mouse.sendHid(0x0004, {});  // thả

// Cuộn lên một bước
mouse.sendHid(0x0800, { WheelDelta: 120 });

// Nhấn nút X1
mouse.sendHid(0x0080, { XButton: 1 });
mouse.sendHid(0x0100, { XButton: 1 });

mouse.sendEvent(eventData, eventType)

Chuyển tiếp sự kiện chuột tùy chỉnh qua hệ thống macro của SignalRGB. Các script macro với trigger onMouse có thể khớp các sự kiện này. Không tiêm nhập liệu chuột OS.

mouse.sendEvent({ button: "LeftClick" }, "ButtonPress");

---

Tính năng pin

Dành cho các thiết bị không dây báo cáo trạng thái pin. Sau khi thêm tính năng, hãy cập nhật mức và trạng thái pin khi thiết bị báo cáo.

export function Initialize() {
    device.addFeature("battery");
}

Đặt trạng thái pin

Phương thức	Mô tả
battery.setBatteryLevel(level)	Đặt phần trăm pin (0–100)
battery.setBatteryState(state)	Đặt trạng thái sạc sử dụng hằng số trạng thái

Hằng số trạng thái (truy cập qua battery.<name>):

Hằng số	Mô tả
battery.disabled	Báo cáo pin bị vô hiệu hóa
battery.unknown	Trạng thái chưa được biết
battery.draining	Đang chạy bằng pin
battery.charging	Đang sạc qua cáp
battery.fullCharging	Đang sạc và đã đầy
battery.full	Đã đầy hoàn toàn, không sạc
battery.wirelessCharging	Đang sạc không dây

Đọc trạng thái pin

Các thuộc tính này phản ánh các giá trị được đặt lần cuối:

Thuộc tính	Kiểu	Mô tả
battery.batteryLevel	Number	Mức hiện tại (0–100)
battery.batteryState	Number	Giá trị trạng thái hiện tại
battery.stateString	String	Nhãn trạng thái có thể đọc được

Ví dụ pin

export function Initialize() {
    device.addFeature("battery");
}

export function Render() {
    // Đọc không chặn — kiểm tra xem thiết bị có gửi báo cáo pin cho khung này không
    var data = device.read([], 64, 0);

    if(device.getLastReadSize() > 0 && data[0] === 0x02) {
        var level = data[1];             // 0–100
        var charging = data[2] === 0x01;

        battery.setBatteryLevel(level);
        battery.setBatteryState(
            charging ? battery.charging : battery.draining
        );
    }
}