Device Scripting

This page aims to explain how to create new device support via scripting with Aurora.

Aurora supports scripting with C# and Python. You can add support for new devices by creating a new script file in Aurora's Directory/Scripts/Devices. You should have two sample scripts located in that folder, "example_script.cs" and "example_py_script.py". You can examine these sample scripts to get a better understanding of how to implement a new device.

Script requirements

Device scripts must include the following variables and function to be properly loaded by Aurora.

Script format

For scripting, C# follows the same format as any other C# class. For Python, you have to define a main class with your variables and function definitions in there. Like so:

Python

class main():
    devicename = "Example Python Device Script"
    enabled = True
    
    def Initialize(self):
        try:
            #Perform necessary actions to initialize your device
            return True
        except:
            return False

Variables

The following set of variables is always required to exist in the script for Aurora to load the script.

• Each device must have a name. Thus you have to include the devicename variable with the name of your device.
• Each device script has to have an enabled boolean variable. This allows users to disable a script from loading and running. A script will only load and run if enabled boolean is set to True.

C#

public string devicename = "Example CS Device Script";
public bool enabled = true;

Python

class main():
    devicename = "Example Python Device Script"
    enabled = True

Functions

Device scripts very closely represent the Device Interface. Not all interfaced methods are required, but they follow through with the same functionalities. Each device must be able to Initialize, Shutdown, Reset, and UpdateDevice lights. Here is a template for C# and Python:

C#

using Aurora;
using Aurora.Devices;
using System;
using System.Collections.Generic;
using System.Drawing;
using System.Linq;

public class ExampleDeviceScript
{
    public string devicename = "Example CS Device Script";
    public bool enabled = true;
    
    private Color device_color = Color.Black;

    public bool Initialize()
    {
        try
        {
            //Perform necessary actions to initialize your device
            return true;
        }
        catch(Exception exc)
        {
            return false;
        }
    }
    
    public void Reset()
    {
        //Perform necessary actions to reset your device
    }
    
    public void Shutdown()
    {
        //Perform necessary actions to shutdown your device
    }
    
    public bool UpdateDevice(Dictionary<DeviceKeys, Color> keyColors, bool forced)
    {
        try
        {
            foreach (KeyValuePair<DeviceKeys, Color> key in keyColors)
            {
                //Iterate over each key and color and send them to your device
                
                if(key.Key == DeviceKeys.Peripheral)
                {
                    //For example if we're basing our device color on Peripheral colors
                    SendColorToDevice(key.Value, forced);
                }
            }
            
            return true;
        }
        catch(Exception exc)
        {
            return false;
        }
    }
    
    //Custom method to send the color to the deivce
    private void SendColorToDevice(Color color, bool forced)
    {
        //Check if device's current color is the same, no need to update if they are the same
        if (!device_color.Equals(color) || forced)
        {
            //NOTE: Do not have any logging during color set for performance reasons. Only use logging for debugging
            Global.logger.LogLine(string.Format("[C# Script] Sent a color, {0} to the device", color));
            
            //Update device color locally
            device_color = color;
        }
    }
}

Python

import clr

clr.AddReference("Aurora")
clr.AddReference("System.Drawing")

from Aurora import Global
from Aurora.Devices import DeviceKeys
from System.Drawing import Color
from System.Collections.Generic import Dictionary
import System

import sys

class main():
    devicename = "Example Python Device Script"
    enabled = True
    device_color = Color.Black
    
    def Initialize(self):
        try:
            #Perform necessary actions to initialize your device
            return True
        except:
            return False
    
    def Reset(self):
        #Perform necessary actions to reset your device
        return
        
    def Shutdown(self):
        #Perform necessary actions to shutdown your device
        return
    
    def UpdateDevice(self, keyColors, forced):
        try:
            for kvp in keyColors:
                #Iterate over each key and color and send them to your device
                
                if kvp.Key == DeviceKeys.Peripheral:
                    #For example if we're basing our device color on Peripheral colors
                    self.SendColorToDevice(kvp.Value, forced)
                    
            return True
        except Exception as e:
            Global.logger.LogLine("[PY Script] Exception: "+str(e))
            
            return False
    
    def CompareColors(self, color1, color2):
        if color1.A == color2.A and color1.R == color2.R and color1.G == color2.G and color1.B == color2.B:
            return True
        else:
            return False
    
    #Custom method to send the color to the deivce
    def SendColorToDevice(self, color, forced):
        #Check if device's current color is the same, no need to update if they are the same
        if not self.CompareColors(color, self.device_color) or forced:
            #NOTE: Do not have any logging during color set for performance reasons. Only use logging for debugging
            Global.logger.LogLine("[PY Script] Sent a color, " + str(color) + " to the device")
            
            #Update device color locally
            self.device_color = color
        return

Optimizations

To prevent constant lighting calls to your device. It is recommended that you keep the color that you apply to the device, and compare it later when another call to UpdateDevice is made. If the two colors are equal, then you should not need to update your device. The template shown above already has this functionality.