EZB Connect By Name icon EZB Connect By Name — Discover EZB WiFi controllers by name, auto-bind connections, avoid IP management; live discovery and multi-EZB support for ARC. Try it →
 

Utility

Everything else: random numbers, converting a value from one range to another, working with bits, waiting until a time of day, running a program or opening a web page on the computer, loading a project, checking for an ARCx update, and shutting down or sleeping the computer.

Where to find it: type Utility. in a Python script, or open the ARCx API view of the script editor and expand Utility

Commands

Command What it does
Utility.Browser Opens a web address in the default web browser of the computer running ARCx, which may not be the browser you are viewing ARCx in.
Utility.CheckForUpdate Checks the Synthiam website for a newer version of ARCx.
Utility.ClearGlobalVariable Deletes a global variable so it no longer exists.
Utility.ControlCommand Sends a control command to a robot skill, found by its window title (not case sensitive), and returns whatever the skill hands back.
Utility.Exec Starts a program on the computer running ARCx and carries on without waiting for it to finish.
Utility.GetBit Checks whether one bit of a number is set (1).
Utility.GetRandom Returns a random whole number from min to max, both included.
Utility.GetRandomUnique Returns a random whole number from min to max, both included, trying not to repeat the number it returned last time.
Utility.LoadProject Stops this script, closes the current project and opens the given one, raising an error if it cannot be found or loaded.
Utility.Map Converts a value from one range to another, such as 0 to 255 into 1 to 180, keeping the result inside the output range.
Utility.SetBits Builds a byte from eight on/off bits, b7 being the highest bit (worth 128) and b0 the lowest (worth 1).
Utility.ShutdownPC Shuts down the computer running ARCx straight away, without saving the project or asking.
Utility.SleepPCHibernate Hibernates the computer running ARCx: what is in memory is saved to disk and it powers off.
Utility.SleepPCSuspend Puts the computer running ARCx to sleep.
Utility.WaitUntilTime Pauses the script until the computer's clock reaches the given hour and minute, checking once a second.

Details

Utility.Browser

Opens a web address in the default web browser of the computer running ARCx, which may not be the browser you are viewing ARCx in.

Utility.Browser(url)
Value Type What it is
url str The web address to open.

Utility.CheckForUpdate

Checks the Synthiam website for a newer version of ARCx. Waits for the reply (up to 4 seconds by default) and raises an error if the website cannot be reached.

Utility.CheckForUpdate()

Gives back: bool. Whether a newer version is available.

Utility.ClearGlobalVariable

Deletes a global variable so it no longer exists. Nothing happens if there is no variable with that name.

Utility.ClearGlobalVariable(globalVariableName)
Value Type What it is
globalVariableName str The variable name, with or without the leading $.

Utility.ControlCommand

Sends a control command to a robot skill, found by its window title (not case sensitive), and returns whatever the skill hands back. Waits while the skill handles it, and raises an error if no skill has that title or the skill fails.

Utility.ControlCommand(controlName, command, *vals)
Value Type What it is
controlName str The window title of the robot skill.
command str The name of the control command.
vals object Any number of values. Any values the command takes.

Gives back: object. The value the robot skill returned, if any.

Utility.Exec

Starts a program on the computer running ARCx and carries on without waiting for it to finish. Raises an error if the program cannot be found.

Utility.Exec(filename)
Utility.Exec(filename, arguments)
Value Type What it is
filename str The program to run, with its path unless it is on the system path.
arguments str Optional. The command line arguments to pass to the program.

Utility.GetBit

Checks whether one bit of a number is set (1). Bit 0 is the lowest bit, worth 1, and bit 7 is worth 128.

Utility.GetBit(value, bitPosition)
Value Type What it is
value int The number to look in.
bitPosition int Which bit to check, 0 being the lowest.

Gives back: bool. Whether the bit is set.

Utility.GetRandom

Returns a random whole number from min to max, both included. The two may be given either way round.

Utility.GetRandom(min, max)
Value Type What it is
min int The lowest number that can be returned.
max int The highest number that can be returned.

Gives back: int. The random number.

Utility.GetRandomUnique

Returns a random whole number from min to max, both included, trying not to repeat the number it returned last time. Returns min when min and max are equal.

Utility.GetRandomUnique(min, max)
Value Type What it is
min int The lowest number that can be returned.
max int The highest number that can be returned.

Gives back: int. The random number.

Utility.LoadProject

Stops this script, closes the current project and opens the given one, raising an error if it cannot be found or loaded. ".arcx" is added when missing, a bare name is looked up in the My Projects folder, and a password protected project needs its password to have been entered earlier this session.

Utility.LoadProject(filename)
Value Type What it is
filename str The project file, with or without a folder and the .arcx extension.

Utility.Map

Converts a value from one range to another, such as 0 to 255 into 1 to 180, keeping the result inside the output range. Raises an error if inputMin and inputMax are equal.

Utility.Map(input, inputMin, inputMax, outputMin, outputMax)
Value Type What it is
input float The value to convert.
inputMin float The low end of the input range.
inputMax float The high end of the input range.
outputMin float The low end of the output range.
outputMax float The high end of the output range.

Gives back: float. The converted value.

Utility.SetBits

Builds a byte from eight on/off bits, b7 being the highest bit (worth 128) and b0 the lowest (worth 1).

Utility.SetBits(b7, b6, b5, b4, b3, b2, b1, b0)
Value Type What it is
b7 bool Whether bit 7 (worth 128) is on.
b6 bool Whether bit 6 (worth 64) is on.
b5 bool Whether bit 5 (worth 32) is on.
b4 bool Whether bit 4 (worth 16) is on.
b3 bool Whether bit 3 (worth 8) is on.
b2 bool Whether bit 2 (worth 4) is on.
b1 bool Whether bit 1 (worth 2) is on.
b0 bool Whether bit 0 (worth 1) is on.

Gives back: int. The byte, 0 to 255.

Utility.ShutdownPC

Shuts down the computer running ARCx straight away, without saving the project or asking. Works on Windows, Linux and macOS, and raises an error if the operating system refuses (on Linux, ARCx's user needs permission to power off).

Utility.ShutdownPC()

Utility.SleepPCHibernate

Hibernates the computer running ARCx: what is in memory is saved to disk and it powers off. On Windows the script carries on once the computer wakes up. Raises an error if hibernation is turned off or not allowed. A Mac goes to sleep instead, as it decides when to hibernate.

Utility.SleepPCHibernate(force, wake)
Value Type What it is
force bool Windows only: whether to hibernate without asking programs first.
wake bool Windows only: whether timers and devices may wake the computer up again.

Utility.SleepPCSuspend

Puts the computer running ARCx to sleep. On Windows the script carries on once the computer wakes up. Raises an error if the operating system refuses.

Utility.SleepPCSuspend(force, wake)
Value Type What it is
force bool Windows only: whether to sleep without asking programs first.
wake bool Windows only: whether timers and devices may wake the computer up again.

Utility.WaitUntilTime

Pauses the script until the computer's clock reaches the given hour and minute, checking once a second. If that time has already passed today it waits until tomorrow, and it returns early if the script is stopped.

Utility.WaitUntilTime(hour, minute)
Value Type What it is
hour int The hour, 0 to 23 (24-hour clock).
minute int The minute, 0 to 59.