The Omega API is a free (closed-source) API script used to maintain and communicate over simulated connections with other Omega API scripts.
The Omega API can be dropped in any modifiable prim's inventory.
The Omega API requires the "[BuildTronics] Omega Configuration" notecard in the same prim's inventory. This notecard configures the API itself and defines the input and output endpoints to list in the Omega HUD.
The Omega API communicates through same-prim (LINK_THIS) link messages by default, so you also need a script in the same prim to send and receive voltages and data via the Omega API. The template script is the easiest way to set this up, but this documentation covers the link message format in detail if you want to make your own script. For advanced applications, you can also control the Omega API remotely from a different prim in the same linkset using the LINKNUM configuration option.
Only one Omega API script should be placed in each prim; however, multiple Omega API scripts may be used throughout a linkset. Each prim with an Omega API script will appear as its own Omega device.
Besides linkset data, the Omega API does not modify the object in any way, so it is usually safe to add or remove to any object without damaging it.
The prim with the Omega API script can be moved, or even physical, although the Omega HUD will not track objects as they move in search mode. However, if the object crosses into a different region, it will no longer be able to communicate with objects it was already connected to.
The Omega API does not communicate outside Second Life, so the API will continue to work without BuildTronics support.
The Omega API automatically manages linkset data using a format that is unlikely to result in naming collisions. While the Omega API will recover linkset data lost due to unlinking, the API does not recover linkset data erased using llLinksetDataDelete, llLinksetDataDeleteFound, and llLinksetDataReset. Therefore, if you are sharing a linkset with a script that uses these functions indiscriminately, the Omega API will not work.
The Omega API has limited free memory and, in extreme circumstances, other scripts can cause it to crash. If that occurs, the Omega API script can be safely replaced with a new copy and its configuration will automatically refresh.
While the Omega API somewhat obfuscates API-to-API communications, the Omega API should not be treated as a secure method of communication. While it is possible to (somewhat securely) validate the source of certain messages by object UUID, assume all communications are subject to sniffing and spoofing. If you need a secure data channel, you should design your own and then encapsulate it within an Omega API connection if desired.
The Omega API can only communicate with other Omega APIs in the same region (any distance is allowed).
The "[BuildTronics] Omega Configuration" notecard is parsed as follows:
Possible options are shown below.
Endpoints are dynamically-allocated connection points on a single device. While some devices may have only one endpoint - such as a lamp with a single 120V input - others may have multiple, such as a switch. Each endpoint may be connected to another endpoint on a different Omega-compatible device as long as it is the same endpoint type.
Electrical endpoints enable the following features:
We recommend using Electrical endpoints wherever possible for maximum interoperability. However, for situations where a voltage value (even a variable one) would be insufficient, any value other than "E" for TYPE can be used to enable plaintext data transmission using OMEGA_DATA and OMEGA_QUERY.
This section only applies for Electrical devices that operate on "mains" electricity.
Since Second Life is based in North America, the Omega system predominantly uses 120V for mains voltage. However, the system does not prevent you from using a nominal mains voltage of 100V or 230V if you wish.
BuildTronics devices support any voltage as long as it is defined as the nominal voltage. For example, to adjust your devices from 120V to 230V, edit the "[BuildTronics] Omega Configuration" notecard to replace "NOMINAL=120" lines with "NOMINAL=230" as needed.
However, we don't recommend doing this because both the input and output devices need to expect the same voltage to work properly, so any changes to one must also be changed in the other. In any event, most end-users do not care about which mains voltage standard is used.
Sends data out of a local endpoint.
llMessageLinked([linknum]
, 0, "OMEGA_SEND", [endpoint_name]
+ "|" + [data]
);
Parameter | Description |
---|---|
[linknum] |
Integer. Must be LINK_THIS unless you are using cross-link communication. If you are using cross-link communication, use the link number with the Omega API script you want to control. |
[endpoint_name] |
String. Must be the NAME of the endpoint to send the data out of. |
[data] |
For Electrical endpoints, float cast as string equal to voltage value to send. For non-Electrical endpoints, any string up to 512 characters. This command supports any characters so can be used safely with any unescaped data, but note that since the ` character is used as a delineator, OMEGA_DATA and OMEGA_QUERY will need to be processed carefully (see note for each). |
This call works in the following ways:
Unless otherwise specified, this call does not return any response.
Sent when the internal circuit breaker state changes on a local input endpoint due to an overvoltage condition or self-reset.
link_message(integer [sender_linknum]
, integer [breaker_closed]
, string "OMEGA_BREAKER", key [endpoint_name]
+ "|" + [v]
+ "|" + [v_nominal]
)
Parameter | Description |
---|---|
[sender_linknum] |
Integer. The link number of the Omega API. |
[breaker_closed] |
Integer (either 0 or 1). Whether the circuit breaker is closed (on, 1) or open (off, 0) for this input endpoint. |
[endpoint_name] |
String. The NAME of this input endpoint. |
[v] |
Float cast as string. The voltage currently received on this input endpoint. |
[v_nominal] |
Integer. The NOMINAL voltage for this input endpoint. |
Sent when data is received on a local input endpoint by using OMEGA_SEND in the connected output object.
link_message(integer [sender_linknum]
, integer 0, string "OMEGA_DATA", key [from_uuid]
+ "|" + [endpoint_name]
+ "|" + [data]
)
Parameter | Description |
---|---|
[sender_linknum] |
Integer. The link number of the Omega API. |
[from_uuid] |
Key. The UUID of the prim with the output endpoint connected to this input endpoint. |
[endpoint_name] |
String. The NAME of this input endpoint. |
[data] |
String. The value of [data] sent by OMEGA_SEND in the output object.This value may include any valid characters, including ` . Therefore, one way to correctly (albeit inefficiently) read this value is as follows:list params = llParseStringKeepNulls( [key] , ["`"], []);[from_uuid] = llList2String(params, 0); // optional[endpoint_name] = llList2String(params, 1); // optional[data] = llDumpList2String(llList2List(params, 2, -1), "`"); |
Sent when data is received on a local output endpoint by using OMEGA_SEND in the connected input object.
link_message(integer [sender_linknum]
, integer 0, string "OMEGA_QUERY", key [from_uuid]
+ "|" + [endpoint_name]
+ "|" + [data]
)
Parameter | Description |
---|---|
[sender_linknum] |
Integer. The link number of the Omega API. |
[from_uuid] |
Key. The UUID of the prim with the input endpoint connected to this output endpoint. |
[endpoint_name] |
String. The NAME of this output endpoint. |
[data] |
String. The value of [data] sent by OMEGA_SEND in the input object.This value may include any valid characters, including ` . Therefore, one way to correctly (albeit inefficiently) read this value is as follows:list params = llParseStringKeepNulls( [key] , ["`"], []);[from_uuid] = llList2String(params, 0); // optional[endpoint_name] = llList2String(params, 1); // optional[data] = llDumpList2String(llList2List(params, 2, -1), "`"); |
Sent when the Omega API has completed its initialization. Useful to know when to set constant-voltage Electrical output endpoints.
link_message(integer [sender_linknum]
, integer 0, string "OMEGA_READY", key [script_name]
)
Parameter | Description |
---|---|
[sender_linknum] |
Integer. The link number of the Omega API. |
[script_name] |
String. The inventory name of the Omega API script. |
Sent when a voltage is set on a local input endpoint by using OMEGA_SEND in the output object, when the endpoint is connected or disconnected, when the breaker state changes, and when the notecard is loaded.
link_message(integer [sender_linknum]
, integer [v_nominal]
, string "OMEGA_V_IN", key [from_uuid]
+ "|" + [endpoint_name]
+ "|" + [v]
)
Parameter | Description |
---|---|
[sender_linknum] |
Integer. The link number of the Omega API. |
[v_nominal] |
Integer. The NOMINAL voltage for this input endpoint. |
[from_uuid] |
Key. The UUID of the prim with the output endpoint connected to this input endpoint. This command is also sent to refresh [v_nominal] in other scripts when the configuration notecard is loaded; in that case, this UUID will be NULL_KEY. |
[endpoint_name] |
String. The NAME of this input endpoint. |
[v] |
Float cast as string. The voltage currently received on this input endpoint. |
Sent when a voltage is set on a local output endpoint by using OMEGA_SEND and when the notecard is loaded.
link_message(integer [sender_linknum]
, integer [v_nominal]
, string "OMEGA_V_OUT", key [endpoint_name]
+ "|" + [v]
)
Parameter | Description |
---|---|
[sender_linknum] |
Integer. The link number of the Omega API. |
[v_nominal] |
Integer. The NOMINAL voltage for this output endpoint. |
[endpoint_name] |
String. The NAME of this output endpoint. |
[v] |
Float cast as string. The voltage currently sent on this output endpoint. |
To enable debug mode, set the "debug" linkset data pair to any value; for example, llLinksetDataWrite("debug", "1"). When in debug mode, all BuildTronics scripts in the same linkset print debug messages via llOwnerSay. To disable debug mode, delete the "debug" linkset data pair using llLinksetDataDelete("debug").