Utilities

Device Utilities

device.color()

This function is your way of fetching color data from the canvas. It takes in an X,Y position relative to and within the device's pixel buffer on the canvas and returns an [R,G,B] array of the color at that pixel.

• Note: the sent X,Y coordinates must be within the Pixel Buffer set by the Size() Export

Below is a cut-down example of the function being used in a typical situation.

for(var iIdx = 0; iIdx < vLedPositions.length; iIdx++) //For each Led on the device  

        {  

            var iPxX = vLedPositions[iIdx][0]; //Get the X and Y values from the [X,Y] array  

            var iPxY = vLedPositions[iIdx][1];  

            var col; // create a variable to contain the [R.G.B] array data  

            if(shutdown){       // Check for some settings that can override the Device.color() call  

                col = hexToRgb(shutdownColor)  

            }else if (LightingMode == "Forced") {  

                col = hexToRgb(forcedColor)  

            }else{  

                col = device.color(iPxX, iPxY);  //Calling Device.color with the X and Y values  

            }  

            //Saving the Color data in order into a larger Array of all the LED's data  

            RGBdata[iIdx*3] = col[0]; // Red Channel   

            RGBdata[iIdx*3+1] = col[1]; //Green Channel  

            RGBdata[iIdx*3+2] = col[2]; //Blue Channel  

            TotalLedCount += 1;  

        }

device.getBrightness()

Returns the devices current brightness level within SignalRGB. This value is already applied to any colors returned by device.color() or similar.

device.getMotherboardName()

Returns the WMI name of the current systems motherboard.

device.pause()

This function attempts to pause the device thread for the given length. These pauses are not guaranteed to be exact due to how the operating system handles thread sleeps.

• Note: Windows has a minimum sleep time of 1-2ms and will start to break down as the sleep gets longer so don't use these for exact timings.

packet[89] = CalculateCrc(packet);

    device.send_report(packet, 91);    

    device.pause(1); // We need a pause here (between packets), otherwise the ornata can't keep up.

device.set_endpoint()

This function changes the active endpoint for all read and write commands. This is useful for devices that have multiple open endpoints for different commands. A common example of this is Logitech devices which have an RGB data endpoint and a system command endpoint for things like DPI settings.

function Apply()

{

    var packet = [];

    packet[0] = 0x11;

    packet[1] = 0xFF;

    packet[2] = 0x0C;

    packet[3] = 0x5E;

​

    device.set_endpoint(1, 0x0602, 0xff43); // System Interface    

    device.write(packet, 20);  

}

device.log()

This function is the plugin's version of console.log. It takes in a String, Number, Object, or Array and logs it in the device's console for debugging and user information. This can be especially useful to list things like DPI changes, errors, or during development to show your packets layout or input from read commands.

• Note: This function will try to convert JavaScript variables to strings where It can. Logging JavaScript Template Literals using parseInt(), toString(), or JSON.stringify can give you more control over conversion and formatting.

let ImportantData = "i have really important info here";

    device.log(ImportantData, {toFile: true})

Alerts

Alerts can be used to visible prompt the user if there's an issue with their device. These should be used sparingly and reserved for show stopping issues like devices not being configured properly.

device.notify()

Creates an new alert for the user. The return value can be used to selectively remove the alert and should be done if the user fixes the alerted issue.

let Alertid = device.notify("Really Important Issue", "Please Fix", 1);

device.denotify()

Removes the given alert if it exists.

let Alertid = device.notify("Really Important Issue", "Please Fix", 1);

  // Do stuff and recheck if the alerted issue is fixed

  device.denotify(AlertId);

Messages

Device messages provide a way to relay important, but not show stopping information to the user. These messages will only appear on the device's page

device.addMessage()

Adds a new device message with the given MessageId.

device.addMessage("message1", "Hey Dude you should know this", "Here's some extra info about it too");

device.removeMessage()

Removes the message created with the given MessageId if one exists.

device.addMessage("message1", "Hey Dude you should know this", "Here's some extra info about it too");

​

  // message is no longer relevant

  device.removeMessage("message1");