common/deviceFns

Dynamic Device method injection utilities for the Total Control scripting system.

This module lets you define and attach custom JavaScript functions to the Device and DeviceArray
prototypes at runtime, so they can be called as native methods (e.g., device.myFn() or
devices.myFn() for multiple devices). It supports both synchronous and asynchronous execution
across multiple devices and provides a safe way to remove injected methods.

It is designed to be used from Userlib.js (Total Control 7.0.0+), where custom behaviors are
registered via addDeviceFunction() and, when needed, removed with delDeviceFunction().

Features

• Register user-defined functions as Device/DeviceArray methods with a chosen alias
• Execute on a single device or broadcast to multiple devices (multiple: true)
• Choose execution mode per function:
  • sync: iterate devices one-by-one
  • async: parallel per-device execution using Java threads
• Automatic argument injection: the target Device instance is prepended to your function’s arguments
• Safe teardown: remove custom methods from Array, Device, and DeviceArray prototypes
• Graceful error handling during dynamic binding (eval guarded with try/catch)
• Backward compatibility defaults for options (sync + single-device if not specified)

Usage Example

// 1) Define the implementation (first parameter will be the Device instance)
function test(dev) {
  dev.print("hello from " + dev.getSN());
}

// 2) Register as a method on Device (and DeviceArray if multiple=true)
//    Note: requires Total Control 7.0.0+ for addDeviceFunction(functionName, fn, option)
addDeviceFunction("testFn", test, { mode: "async", multiple: true });

// 3) Invoke on one device
var { Device } = require("sigma/device");
var d = Device.getMain();
d.testFn(); // calls `test(d)`

// 4) Invoke across many devices in parallel
var all = Device.searchObject(sigmaConst.DevAll);
if (all) all.testFn();

// 5) Remove the injected method if no longer needed
delDeviceFunction("testFn", true); // verbose deletion logs

Integration

• Methods are dynamically attached to Device.prototype and, when multiple: true, also to DeviceArray.prototype.
• In async mode, each device call runs in its own Java thread and the wrapper waits until all complete.
• The injected method receives the target device as its first argument automatically.

Notes

• Custom registrations should be placed in Userlib.js; check Script List to locate/edit it.
• API availability:
  • addDeviceFunction(functionName, function, option) is supported in Total Control 7.0.0+.
• Deletion (delDeviceFunction) attempts removal from Array.prototype, Device.prototype,
  and DeviceArray.prototype, returning true if the process completes.

Functions

// Example: Add a custom method `testFn` to each device that prints a message.

// Define the custom function to be executed
function test() {
    print("this is test");
}

// Register the function as a method called `testFn` on device objects
addDeviceFunction('testFn', test, { mode: 'async', multiple: true });

// Get all available devices
var devices = Device.searchObject(sigmaConst.DevAll);

if (devices != null) {
    // Call the newly added method on all found devices
    devices.testFn();
} else {
    print("Failed to get the master device object");
}

// Expected output (if two devices are connected):
// this is test
// this is test

// Define a custom method `click2` on the Device prototype
function myclick(d, x, y) {
    d.click(x * 2, y * 2);
}
Device.prototype.click2 = myclick;

// Use the custom method
var device = Device.getMain();
device.click2(device, 100, 100);

// Delete the custom method using delDeviceFunction
var ret = delDeviceFunction('click2');
if (ret === true) {
    print("Method successfully deleted");
} else {
    print("Failed");
}

// Running result (if successful):
// Method successfully deleted