Device Control API

RSS

The DeviceControl class provides programmatic access to device properties and methods and scripting via a simple API allowing remote control and monitoring of Elve devices.

The machine using the API must either:

Be the same machine running the Elve Master Service.
or have a MachineSettings.config file here: C:\ProgramData\Codecore Technologies\Elve\MachineSettings.config

Restrictions:

Access to this class is restricted to Elve user accounts which have 3rd party remote access and control access enabled.
Do not use these methods from within a Device Driver. The Driver class already has implementations of these methods.

Table of Contents [Hide/Show]

Example

Here is a quick example:


using CodecoreTechnologies.Elve.RemoteAccess;
    
DeviceControl devControl = null;
try
{
    devControl = new DeviceControl("admin", "admin");
}
catch (SocketException ex)
{
    // TODO: failed to connect to master service
}
catch (Exception ex)
{
    // TODO: user account does not have access
}

try
{
    // Set a device property (an array element in this example)
    devControl.SetDevicePropertyValue("lighting", "LightLevels", 5, new ScriptNumber(25));

    // Get a device propery (an array element in this example)
    IScriptObject so = devControl.GetDevicePropertyValue("lighting", "LightLevels", 5);

    // Invoke a device method
    devControl.InvokeDeviceMethod("lighting", "TurnOnLight", new ScriptNumber(5));

    // Run a script
    devControl.RunScript("my script", "lighting.SetLightLevel(5, 50);", true);
}
catch (SocketException ex)
{
    // TODO: failed to connect to master service
}
catch (Exception ex)
{
    // TODO: a variety of other exceptions may occur, for example if the device is not running, etc.
}

Devices Class Members

The Devices class provides support for getting and setting property values, invoking methods and running scripts programatically.

Constructors

Devices( string username, string password )

Initializes the Devicesobject. The specified user account must have 3rd party remote control access enabled.

Syntax

System.Boolean StartDriver( Dictionary configFileData )

Parameters

username: The username.

password: The password.

Exceptions

SocketException : Failed to fully communicate with the Master Service.

Exception : The user account does not have access, the client configuration file could not be read, or the communications layer could not be set up.

Instance Methods

InvokeDeviceMethod( string deviceName, string methodName, params IScriptObject[] parameterValues )

Invokes the specified device method. This allows a device to invoke a method on any other device. Do not use this to invoke a method in the current device as that would be very inefficient. This method will throw an exception if the device method is inaccessible, for example if the device is disabled, the driver service isn't running, or the device doesn't exist.

Syntax

IScriptObject InvokeDeviceMethod( string deviceName, string methodName, params IScriptObject[] parameterValues )

Parameters

deviceName : The name of the device (also known as scripting identifier or alias) (case insensitive).

methodName : The name of the device method (case insensitive).

parameterValues : The parameter values to pass to the method in the order they are declared.

Return Value

The result of the method invocation.

Exceptions

SocketException : Failed to fully communicate with the Master Service.

GetDevicePropertyValue(string deviceName, string propertyName)

Gets the value of the specified device and property. This allows a device to retrieve a property value from any other device. Do not use this to get a property value from the current device as that would be very inefficient. This method will throw an exception if the device property is inaccessible, for example if the device is disabled, the driver service isn't running, or the device doesn't exist.

Syntax

IScriptObject GetDevicePropertyValue(string deviceName, string propertyName)

Parameters

deviceName : The name of the device (also known as scripting identifier or alias) (case insensitive).

propertyName : The name of the device property (case insensitive).

Returns

The value of the device property.

Exceptions

SocketException : Failed to fully communicate with the Master Service.

Example:


try
{
    ScriptBoolean sb = (ScriptBoolean)GetDevicePropertyValue("lighting", "DeviceIsReadyForUse");
    bool b = (bool)sb;
}
catch
{
    // failed to retrieve property. (The device may not exist, may be disabled, the driver service might not be connected, etc.)
}

GetDevicePropertyValue(string deviceName, string propertyName, int propertyIndex)

Gets the value of a property array element from a device. This allows a device to retrieve a property value from any other device. Do not use this to get a property value from the current device as that would be very inefficient. This method will throw an exception if the device property is inaccessible, for example if the device is disabled, the driver service isn't running, or the device doesn't exist.

Syntax

IScriptObject GetDevicePropertyValue(string deviceName, string propertyName, int propertyIndex)

Parameters

deviceName : The name of the device (also known as scripting identifier or alias (case insensitive)).

propertyName : The name of the device property array (case insensitive).

propertyIndex : The index of the array element to get.

Returns

The value of the device property.

Exceptions

SocketException : Failed to fully communicate with the Master Service.

Example:


try
{
    ScriptNumber sb = (ScriptNumber)GetDevicePropertyValue("lighting", "LightLevels", 12); // get the light level value for light #12.
    int = (int)sb;
}
catch
{
    // failed to retrieve property. (The device may not exist, may be disabled, the driver service might not be connected, etc.)
}

SetDevicePropertyValue(string deviceName, string propertyName, IScriptObject value)

Sets the value of the specified device property. This allows a device to set a property value in any other device. Do not use this to set a property value in the current device as that would be very inefficient. This method will throw an exception if the device property value can not be set, for example if the device is disabled, the driver service isn't running, or the device doesn't exist.

Syntax

void SetDevicePropertyValue(string deviceName, string propertyName, IScriptObject value)

Parameters

deviceName : The name of the device (also known as scripting identifier or alias) (case insensitive).

propertyName : The name of the device property (case insensitive).

value : The value to set the property to.

Exceptions

SocketException : Failed to fully communicate with the Master Service.

SetDevicePropertyValue(string deviceName, string propertyName, int propertyIndex, IScriptObject value)

Sets the value of the specified device property array element. This allows a device to set a property value in any other device. Do not use this to set a property value in the current device as that would be very inefficient. This method will throw an exception if the device property is inaccessible, for example if the device is disabled, the driver service isn't running, or the device doesn't exist.

Syntax

void SetDevicePropertyValue(string deviceName, string propertyName, int propertyIndex, IScriptObject value)

Parameters

deviceName : The name of the device (also known as scripting identifier or alias) (case insensitive).

propertyName : The name of the device property (case insensitive).

propertyIndex : The index of the array element to set.

value : The value to set the property to.

Exceptions

SocketException : Failed to fully communicate with the Master Service.

ToggleBooleanDevicePropertyValue(string deviceName, string propertyName)

Toggles the specified boolean device property's state. Do not use this to toggle a boolean property value in the current device as that would be very inefficient. This method will throw an exception if the device property is inaccessible, for example if the device is disabled, the driver service isn't running, or the device doesn't exist.

Syntax

void ToggleBooleanDevicePropertyValue(string deviceName, string propertyName)

Parameters

deviceName : The name of the device (also known as scripting identifier or alias) (case insensitive).

propertyName : The name of the device property (case insensitive).

Exceptions

SocketException : Failed to fully communicate with the Master Service.

ToggleBooleanDevicePropertyValue(string deviceName, string propertyName, int propertyIndex)

Toggles the specified boolean device property array element's state. Do not use this to toggle a boolean property value in the current device as that would be very inefficient. This method will throw an exception if the device property is inaccessible, for example if the device is disabled, the driver service isn't running, or the device doesn't exist.

Syntax

void ToggleBooleanDevicePropertyValue(string deviceName, string propertyName, int propertyIndex)

Parameters

deviceName : The name of the device (also known as scripting identifier or alias) (case insensitive).

propertyName : The name of the device property (case insensitive).

propertyIndex : The index of the boolean array element to toggle.

Exceptions

SocketException : Failed to fully communicate with the Master Service.

OffsetNumericDevicePropertyValue(string deviceName, string propertyName, double offset)

Increments or Decrements the specified numeric device property's value. The property type must be ScriptNumeric. Do not use this to offset a numeric property value in the current device as that would be very inefficient. This method will throw an exception if the device property is inaccessible, for example if the device is disabled, the driver service isn't running, or the device doesn't exist.

Syntax

void OffsetNumericDevicePropertyValue(string deviceName, string propertyName, double offset)

Parameters

deviceName : The name of the device (also known as scripting identifier or alias) (case insensitive).

propertyName : The name of the device property (case insensitive).

offset : The positive or negative value to offset the current property value by.

Exceptions

SocketException : Failed to fully communicate with the Master Service.

OffsetNumericDevicePropertyValue(string deviceName, string propertyName, int propertyIndex, double offset)

void OffsetNumericDevicePropertyValue(string deviceName, string propertyName, int propertyIndex, double offset)

Parameters

deviceName : The name of the device (also known as scripting identifier or alias) (case insensitive).

propertyName : The name of the device property (case insensitive).

propertyIndex : The index of the boolean array element to offset.

offset : The positive or negative value to offset the current property value by.

Exceptions

SocketException : Failed to fully communicate with the Master Service.

RestartDevice( string deviceName )

Restarts a device in the Elve system.

Syntax

void RestartDevice( string deviceName )

Parameters

deviceName : The name of the device to restart.

Return Value

none

Exceptions

SocketException: Failed to fully communicate with the Master Service.

RunScript(string scriptName, string script, bool throwError)

Run a script.

Syntax

IScriptObject RunScript(string scriptName, string script, bool throwError)

Parameters

scriptName : The name of the script to use when logging errors.

script : The script contents to run.

throwError : Indicates if an exception should be thrown if an error occurs when running the script.

Returns

The return value of the script.

Exceptions

SocketException : Failed to fully communicate with the Master Service.

RunScript(string scriptName, string script, bool throwError, bool runAsync, params object[] variables_Name_comma_IScriptObject)

Run a script.

Syntax

IScriptObject RunScript(string scriptName, string script, bool throwError, bool runAsync, params object[] variables_Name_comma_IScriptObject)

Parameters

scriptName : The name of the script to use when logging errors.

script : The script contents to run.

throwError : Indicates if an exception should be thrown if an error occurs when running the script.

runAsync : Indicates if the script should be run asynchronously and the method should be non-blocking.

variables_Name_comma_ScriptObject : An alternating list of variable name and variable values. Ex: "var1", var1, "var2", var2. Where var1 and var2 are of type IScriptObject.

Returns

The return value of the script.

Exceptions

SocketException : Failed to fully communicate with the Master Service.