The light bus is the main communications system for interactions between the main controller (MC) and compatible hardware. It was originally designed for use with attached devices (peripherals) and carried information relevant to lighting effects, such as the system's illumination color and the power state. Although still mostly stateless, it has over time grown into an elaborate protocol that can be used to mediate everything from recharging weapons (see separate article on combat-related protocols) to user authentication for control via a device.
Light bus messages are processed on a user-specific channel, generated by the following rule:
channel_lights = 105 - (integer)("0x" + llGetSubString(llGetOwner(), 29, 35));
There are two general categories of devices, passive and active. A passive device is one that simply listens on this channel for relevant messages and reacts accordingly. Status lights, eyes, and reactive clothing are good examples of passive devices, as they do not generally need to request specific system information, obtain permission for user interaction, or instruct the controller to carry out a task.
Active devices are those that have sent an add <device> message and received an add-confirm message in response. (See below.) Once a device has been marked as active, it may use the messages listed under the 'active (device to MC)' section. Devices belonging to the unit, such as attachments, can expect to be confirmed as active devices immediately; other devices, called foreign devices, must be granted access according to the local access permissions of their owner.
Unless otherwise specified, tokens on the light bus are separated exclusively by spaces. For some messages, this may mean that llParseString2List()-based parsing is inadequate, as e.g. unquoted and unescaped string arguments may follow; for these messages, when the initial keyword is detected, switch to using llGetSubString() to extract the remaining text, or llDumpList2String(llList2List(...), " ") to re-concatenate the parameters.
<device> in the messages below represents the short, one-word description of the device's component role, e.g. 'horns' or 'icon'. It must not contain spaces. This is sometimes known as the device name, but should not be confused with the object name of the device. See note at name <name> regarding recommended object name formats.
New in Companion 8.4 and ATOS 12.1 is the ability to connect to ports. These are particle targets used to enhance the unit's appearance when connected to other devices. The supported port types are: power, data-1, data-2, audio-in, and audio-out. Some controllers may include some or all of these port types by default, but peripherals can specify replacements using the port message much like they use the add message (in response to probe, attach, etc.)
passive messages
These messages are sent automatically by the controller over the light bus channel. They are available even to devices that have not authenticated.
The safety bolts have been engaged or disengaged. This corresponds to the underlying state imposed by the @bolts command. If the bolts are on, then peripherals should be locked in place (@detach=n in RLV); if they are off, then the detachment restriction should be released (@detach=y). The automatic bolts setting (release when powered down) is handled by the controller, so it is unnecessary to check whether the system power is on before reacting to the bolts message over the light bus.
This message is sent to newly-authenticated active devices immediately following the add-confirm message.
This message is sent to newly-authenticated active devices immediately following the add-confirm message.
The unit has entered or left the 'broken' state, which indicates that it has been damaged. Apply appropriate sound and visual effects. This is applied automatically in response to ATOS damage, as well as briefly following a teleport. Additionally, it may be manually controlled with the !broken and !fixed cortex commands.
The unit is being carried by the avatar <key> using the handle device at address point <device>. If no handle applies, then <device> will be "none".
The actual charging process has begun or ended. Apply visual effects as appropriate. This message will be sent even when connecting to a stative wireless charger, such as a Destruir Technologies Wireless Charging Station.
The system's current color, measured in floating point (i.e., each value must be in the range [0, 1].) Sent whenever it changes, or in response to the color-q message.
The system's current secondary color, measured in floating point (i.e., each value must be in the range [0, 1].) Sent whenever it changes, or in response to the color-q message. By convention, the secondary color is recommended for indicating a positive situation or outcome on devices and may default to green.
The system's current tertiary color, measured in floating point (i.e., each value must be in the range [0, 1].) Sent whenever it changes, or in response to the color-q message. By convention, the tertiary color is recommended for indicating a negative situation or outcome on devices and may default to red or orange.
The system's current quaternary color, measured in floating point (i.e., each value must be in the range [0, 1].) Sent whenever it changes, or in response to the color-q message. By convention, the quaternary color is recommended for indicating a concerning or urgent situation on devices and may default to yellow.
There is a device at address <device> with the key <key>. This is normally only sent to the HUD, either in response to a device addition or in bulk when the HUD is installed. This message is deprecated in 8.6 in favor of device-list, which is more efficient.
The current fan speed, measured from 0 to 100.
The unit has been instructed to follow the avatar or object <target>. This can be requested with the follow-q message. Devices such as collars may desire this information so they can send leash particles. If the unit is not following anyone or anything, then <target> will be NULL_KEY.
The unit's motors have been locked in place (or released) for some reason other than normal disablement of the movement subsystem. This commonly occurs during charging, or when carried using a handle device.
Reports the system's current gender settings for the attribute <topic>. Supported topics are physical, mental, or voice. For <value>, the format varies by topic; physical and mental genders will describe a full set of comma-separated pronouns and the name of the gender, while voice gender only supplies the name of the gender.
Examples:
Examples:
- The unit's physical gender is 'inanimate': gender physical its,its,it,it,itself,inanimate
- The unit's mental gender is 'female': gender mental hers,her,she,her,herself,female
- The unit's voice gender is 'male': gender voice male
Correct usage in role play: It is recommended that the physical gender be used to specify pronouns in emotes, e.g. /me uses <physical possessive pronoun> charger., and the mental gender be used when the unit speaks about itself, e.g. /me says, "This unit is <mental subject pronoun> whom you seek.". Voice gender should be used only to decide what sort of vocalizations to play; e.g. a grunt of pain or pleasure might be based on voice gender.
Less obviously, Speech Standard 1 dictates that physical gender be used when speaking about another, not mental gender; units abiding by SS1 regard their physical gender as the "truth" and mental gender (especially if inanimate) as a form of subjugation. While this is contrary to the experience of organic gender minorities, it synergizes well with gender transformation fantasies: in most such scenarios, a physical change may precede a mental one if they are not simultaneous, and the very act of assuming another's physical gender to be accurate plays into the reinforcement process of the acceptance of change. Personas and other scripts may elect to use such "forward-looking" or "objective" pronouns to refer to the unit in canned speech if it facilitates an intentional change in identity.
Less obviously, Speech Standard 1 dictates that physical gender be used when speaking about another, not mental gender; units abiding by SS1 regard their physical gender as the "truth" and mental gender (especially if inanimate) as a form of subjugation. While this is contrary to the experience of organic gender minorities, it synergizes well with gender transformation fantasies: in most such scenarios, a physical change may precede a mental one if they are not simultaneous, and the very act of assuming another's physical gender to be accurate plays into the reinforcement process of the acceptance of change. Personas and other scripts may elect to use such "forward-looking" or "objective" pronouns to refer to the unit in canned speech if it facilitates an intentional change in identity.
The system has been exposed to ACS interference, described here. The <type> field is a string consisting of the single-character constants for each class of interference, concatenated together. For practical reasons, these are indicated based on the types of function impairment they cause.
For example, a type of "MCY" indicates that motor control, cortex operation, and memory access are all impaired. At the conclusion of interference, "interference-state " is sent, with a trailing space.
| class | effects |
|---|---|
| M | Impairment of motor control |
| C | Impairment of cortex operation |
| S | Impairment of sound (speech) output |
| N | Impairment of sensory functions |
| Y | Impairment of memory access |
For example, a type of "MCY" indicates that motor control, cortex operation, and memory access are all impaired. At the conclusion of interference, "interference-state " is sent, with a trailing space.
The current unit name, including the prefix. Peripherals that can be interacted with by a user are encouraged to name themselves according to the full unit name plus a description in parentheses. This should be performed whenever a name message is sent, or immediately after receiving add-confirm based on the object name given in the name parameter of the listen() event. The name message is only sent when there is an update to this value.
For example, the chromatic communicator icon attached to an SXD unit named vi0let should take the unit's full name (SXD vi0let) and append " (icon)" to the end, resulting in the full name SXD vi0let (icon). This provides a consistent interface when interacting with a unit's peripherals. However, vi0let's battery does not need to rename itself, as it is not part of the unit's body and does not have any interactive features during regular use.
For example, the chromatic communicator icon attached to an SXD unit named vi0let should take the unit's full name (SXD vi0let) and append " (icon)" to the end, resulting in the full name SXD vi0let (icon). This provides a consistent interface when interacting with a unit's peripherals. However, vi0let's battery does not need to rename itself, as it is not part of the unit's body and does not have any interactive features during regular use.
Indicates the state of system main power. ("on" will be sent when the unit is powered on, and "off" when it is shut down.) No messages are sent when the unit enters or leaves auxiliary power mode. For various reasons, such as in response to the power-q message, this may be re-sent without the unit changing power state, so any devices that have boot-up or shut-down actions should store the current power state and verify that the power state has changed before taking action.
The unit's active persona is now <name>. Sent in response to persona-q, or when the persona changes. If no persona is active, then <name> is default.
Indicates the current level of power remaining, measured as a fraction of total capacity from 0.0 to 1.0. This is sent when the battery is connected, or whenever the integral percentage changes (e.g. 99% to 98%.) It can also be triggered manually with the power-q message.
The net rate of power consumption, measured in J/s. When power is received from an exterior source, this value is lessened, and is typically negative during charging.
Subsystem <SS> is either on (1) or off (0), where <SS> is a numeric value indicating:
These values were changed in Companion 8.4 to be more consistent. See practical breakdown here.
| subsystem | numeric value |
|---|---|
| VIDEO | 1 |
| AUDIO | 2 |
| MOVE | 4 |
| TELEPORT | 8 |
| RAPID | 16 |
| VOICE | 32 |
| MIND | 64 |
| PREAMP | 128 |
| POWER_AMP | 256 |
| RADIO_IN | 512 |
| RADIO_OUT | 1024 |
| GPS | 2048 |
| IDENTIFY | 4096 |
These values were changed in Companion 8.4 to be more consistent. See practical breakdown here.
See combat protocols.
The FTL subsystem is refreshing, and the unit will be unable to teleport for <time> more seconds. Sent every second.
See combat protocols.
The unit has entered or left the 'working' state, which indicates that it is currently performing a calculation or other processing task. Play appropriate lighting and sound effects. This is triggered automatically during vox filter processing, or manually, with the !working and !done cortex commands.
active messages (device to MC)
The sender is requesting to be identified to the system at address <device>, where <device> is a one-word mnemonic describing the class of peripheral or machine, e.g. icon or battery. No two connected devices may have the same address at the same time. For peripherals, the add message should be sent in response to an on_rez() or attach() event, or in response to the probe message. The controller will respond with either add-confirm or add-fail.
Variant of add. See Packaging for information on the <version> syntax used.
This syntax is used to block old, incompatible devices from being used with newer OSes, which usually do not send a <version> at all. Consequently this syntax is required for HUD and shield devices, and it has also been used to block incompatible battery devices in earlier versions.
This syntax is used to block old, incompatible devices from being used with newer OSes, which usually do not send a <version> at all. Consequently this syntax is required for HUD and shield devices, and it has also been used to block incompatible battery devices in earlier versions.
For devices with updatable firmware, this message should be sent instead of the normal add message. The controller's package manager will recognize the device as an upgradable package, with the name format <device>_<version>. This message syntax is required for the chassis device, as the CSU syntax changed significantly during 8.5, and the EXB-8505 is firmware-update capable.
During the firmware update process, <PIN> will be passed by the package manager to the package installer in cleartext, along with the root UUID of the device. The package installer is responsible for translating this into the actual secret number. See Packaging for more information on version syntax and how to create an updatable device.
During the firmware update process, <PIN> will be passed by the package manager to the package installer in cleartext, along with the root UUID of the device. The package installer is responsible for translating this into the actual secret number. See Packaging for more information on version syntax and how to create an updatable device.
Registers a new federated system command (an @ command) with the controller. This will be available until the device is removed or the controller next probes for the device (e.g., at login.) When the command is received, the command message will be sent to the device.
Asks the controller to verify that the user <key> has local access. If the user is authorized, then the controller will respond with accept <key>. This message may take some time to process if consent is required. If the user is not authorized, then the controller will notify him or her directly, and the device will not receive any response. Devices should obtain permission for the user to act immediately upon user contact and avoid caching any commands or actions that may require authorization.
For more complex security interactions, see 205 SEC_PROGRAMMABLE_LOCAL and 210 SEC_PROGRAMMABLE_REMOTE, which may be utilized through the internal message.
See support article for relevant definitions pertaining to access types, user ranks, and consent.
For more complex security interactions, see 205 SEC_PROGRAMMABLE_LOCAL and 210 SEC_PROGRAMMABLE_REMOTE, which may be utilized through the internal message.
See support article for relevant definitions pertaining to access types, user ranks, and consent.
The unit is currently being carried by the avatar <key> using the handle <device>. When carrying stops, the message will be sent with <key> = NULL_KEY. This message should be accepted from any attachment. The controller will send it in response to carrier-q.
Instructs the controller to send carrier.
Removes values from the system settings store. See conf-get for syntax notes.
Retrieves <setting-name> from the configuration manager (_balance/SettingsService). If the setting exists, a conf message is returned. Multiple settings may be retrieved by separating their names with a linebreak, e.g.
These will be returned with a single conf message, such as:
conf-get boot.model
boot.serial
boot.serial
These will be returned with a single conf message, such as:
conf boot.model DAX/2
boot.serial 998123456
boot.serial 998123456
Updates settings kept in the configuration manager (_balance/SettingsService). As with conf-get, multiple directives may be issued in a single message by separating them with linebreaks:
conf-set mydevice.myfeature 1
mydevice.otherfeature myvalue
mydevice.otherfeature myvalue
Instructs the controller to send a list of connected devices (using multiple device-list messages.) If installed, the ATOS security enhancements module will also send the weapon-active message to the destination key, which is normally only sent to the HUD.
Sends the follow message.
Queries the controller's current gender settings. <topic> must be one of physical, mental, or voice. Sends gender in response; see that entry for recommended usage of each gender topic.
Relay a linked message through the controller, i.e., trigger an internal system function. The set of supported linked messages can be found here. To send a system command (such as those listed here), use a <number> value of 0 and the <key> of the user interacting with the device, or the unit's own key (from llGetOwner()) if no such user applies. Most system commands will accept NULL_KEY as a root user.
For example, to turn off the unit, try: internal <device> 0 00000000-0000-0000-0000-000000000000 off
This command is guaranteed to not work unless the device has first authenticated with add.
In Companion 8.5 and later, all internal calls are wrapped as TASK_START messages (see best practices for 8.5 application development) to ensure backward compatibility.
For example, to turn off the unit, try: internal <device> 0 00000000-0000-0000-0000-000000000000 off
This command is guaranteed to not work unless the device has first authenticated with add.
In Companion 8.5 and later, all internal calls are wrapped as TASK_START messages (see best practices for 8.5 application development) to ensure backward compatibility.
The device <device> is currently using <W> watts of power to perform the task named <task>. Loads must be uniquely named, so re-sending a message with the same task name will update the usage for that device/task combination. When the task is completed, send this message with a wattage of 0 to remove the load; loads are also removed when the device is detached.
Task names should be a single word reflecting the reason why the device needs the power, for example load shield recharge 100. These burdens are shown by the power system command, under the section 'external loads.'
Task names should be a single word reflecting the reason why the device needs the power, for example load shield recharge 100. These burdens are shown by the power system command, under the section 'external loads.'
Instructs the controller to send persona.
When this message is produced by a device instead of the controller, it signals that the prim <key> can provide port functionality of the type <type>. This means that it should be used as a particle target for wires emitted by base stations. Port types supported by Nanoconnectivity 1.6:
Note that if the controller sends this message, it instead indicates a redirect to another device; see port-real and the entries above it.
| class |
|---|
| power |
| audio-in |
| audio-out |
| data-1 |
| data-2 |
Note that if the controller sends this message, it instead indicates a redirect to another device; see port-real and the entries above it.
For use by external devices, such as a charging station or other appliance. The sender wishes to connect a cable to a port of the indicated type (see port). The controller will respond with one of two messages:
- If it responds with port <type> <key>, then the accessor should re-send the port-connect query to <key>, which is the actual port host responsible for managing connections. This occurs most often if the host can handle many simultaneous connections of the same type.
- If it responds with port-real <type> <key>, then the accessor should accept the key provided as the particle destination and begin effects as appropriate.
The port of indicated type is no longer in use; see port and port-connect for an explanation of how ports work. The attaching device (i.e., the one that sent port-connect in the first place) must still stop sending particles. Unlike port-connect, the controller is guaranteed to forward this properly to the port host.
Removes the device from the device manager. Most peripherals do not need to do this, but it is appropriate for foreign devices (e.g. docking stations) to do so. Standard batteries also send this message when ejected. As with many active messages, the <device> name must be registered to the UUID sending the message.
The device supports Xanadu-assisted firmware updates. It is currently running the <version> release of its code, and can be updated with a package using the PIN provided. Updater packages and device firmware should both apply salt to the PIN in some manner, and send only the portion of the PIN that excludes the salt.
See combat protocols.
active (MC to device)
Yes, <key> has permission to operate the unit. Sent in response to auth or auth-compare messages.
The device was successfully installed and may now send active commands.
Device installation unsuccessful; usually caused by another device in the same slot or refusal of a foreign connection.
The user has typed @<command> <parameters>; handle accordingly.
Returns the value of a specified setting in response to a conf-get query. If multiple requests were made in the original message, then they will be returned separated by linebreaks.
See combat protocols.
Sends the device address/key relation over the light bus. Multiple messages may be sent if the whole list is more than 240 characters (around 5 devices), so if caching the output of this message, clear the stored value before sending devices, not when receiving it.
See combat protocols.
The user <id> has requested the device's status. Send chat containing this information to <id> on channel 0.
The user <id> has requested access to the device's menu interface. Present some form of UI (llDialog(), hotlinked text, Facet welcome, etc.) to <id>. If using a nonstandard presentation mode (e.g. Facet), warn the user on channel 0. Note also that hotlinked text is incompatible with the controller's chat forwarding mode; depending on the device in question it may be sensible to warn users of this, too.
The indicated policy is in the given state. State information is usually 1 (enforced) or 0 (unenforced), although the 'radio' policy uses 1 to indicate users only and 2 to indicate owners only.
The curfew policy will provide additional information: <state> <time> <triggered> <home_sim> <home_pos>
The curfew policy will provide additional information: <state> <time> <triggered> <home_sim> <home_pos>
The key indicated can provide port functionality of the type. Resend request, to <key>. This message is sent in response to a port-connect query by hardware that wishes to connect a cable to the system.
Something is connecting to the device that receives this message. Trigger connect effects.
Something is disconnecting from the device that receives this message. Trigger disconnect effects.
Send cable particles to <key>. This message is sent in response to port-connect if the controller itself has ports on it.
The main controller's device manager has been reset. All devices that wish to use active messages must send the add message again to register with the controller, or they will be rejected.
Uninstallation successful; proceed.
Uninstallation not successful, don't proceed (e.g. removing a battery while the power is on)
See combat protocols.
sxdwm (exhibition 4) session <session-number> has been created for <key>.
See combat protocols.
See combat protocols.
device-to-device messages
If the receiving device has holographic elements, it should implement the following:
- Maintain a list of holo-blockers. This is a collection of keys that are preventing ("blocking") the holographic elements from being shown.
- Check the list of holo-blockers in a timer and whenever the unit is powered on. Keys stay on this list while they are either:
- the OBJECT_ROOT of the unit (i.e., its chair), or
- in the attachment list of the unit.
- the OBJECT_ROOT of the unit (i.e., its chair), or
- When the list of holo-blockers is empty, the holographic elements can be shown again, and it is no longer necessary to periodically check the list. Remember to ensure that holographic elements are not visible while the unit is powered down.
Sent by some devices over the light bus when they are installed. <device> is the device's one-word name, not its key. Implementation of this message is mandatory for batteries, but is not otherwise used.
Sent by some devices over the light bus when they are removed. <device> is the device's one-word name, not its key. Implementation of this message is mandatory for batteries, but is not otherwise used.
Any active device (see preamble at top of light bus article) may send this message to the HUD device to change its appearance on the HUD.
<uuid> should be the UUID of a texture icon to use, ideally a 32x32 pixel image or larger that has been designed to look good at 16x16 pixels, and consists of only white, transparent, and translucent white pixels.
Only works if using Native 8.6.3 and later. Builds before Oct 6, 2021 do not support this feature. Screen does not support this feature (see add-section instead.)
icon messages should generally be sent in response to the icon-q message, back to the key that sent the icon-q message. You can also determine the correct target for this message by sending devices to the controller.
<uuid> should be the UUID of a texture icon to use, ideally a 32x32 pixel image or larger that has been designed to look good at 16x16 pixels, and consists of only white, transparent, and translucent white pixels.
Only works if using Native 8.6.3 and later. Builds before Oct 6, 2021 do not support this feature. Screen does not support this feature (see add-section instead.)
icon messages should generally be sent in response to the icon-q message, back to the key that sent the icon-q message. You can also determine the correct target for this message by sending devices to the controller.
Sent by HUD in later builds of 8.6.3 and newer to request that the recipient device send an icon message.
Something is connecting to the device that receives this message. Trigger connect effects.
Something is disconnecting from the device that receives this message. Trigger disconnect effects.
Send cable particles to <key>.
Sent by some devices over the light bus when they are re-installed. <device> is the device's one-word name, not its key. Implementation of this message is mandatory for batteries, but is not otherwise used.
device-specific active messages
Adds a button to the custom section <section-name> on the Screen Console Manager HUD. The section must have previously been created using add-section. <icon> should be the UUID for a white-and-transparent texture not exceeding 128x128 px. <command ...> may be multiple words, space-separated; in the event the button is pressed, it will be sent as a 1 COMMAND system command message to the controller with the console as the executing user.
If add-button fails, the device will be sent an add-button-fail message; otherwise it will receive add-button-confirm.
There is no way to remove or modify a button or section from the Screen Console Manager once it has been added.
If add-button fails, the device will be sent an add-button-fail message; otherwise it will receive add-button-confirm.
There is no way to remove or modify a button or section from the Screen Console Manager once it has been added.
Sent by Screen Console Manager to another device. Indicates that a button was successfully added to the section <section-name> by that device using add-button.
Sent by Screen Console Manager to another device. Indicates that a button could not be added to the section <section-name> by that device using add-button. This error message is sent only if the section is already full; no error is produced if the section does not exist. If you are uncertain as to whether the section exists or not, send add-section again; the message will be ignored if the section already exists.
Sent from any device to the Screen Console Manager (_screen) HUD. Adds a new section; the HUD will reply with add-section-confirm. <name> should be a short unique identifier, such as the device address; <width> is the number of icons that the device intends to display. Not supported by the Native Console (_native) HUD; see icon-q instead.
It is not possible to add custom gauges or meters to the Screen HUD. There is no way to remove or modify a button or section from the Screen Console Manager once it has been added.
It is not possible to add custom gauges or meters to the Screen HUD. There is no way to remove or modify a button or section from the Screen Console Manager once it has been added.
Sent by the Screen console to the device that sent add-section, instructing it to proceed with add-button messages.
Sent by HUD (_console-screen) to main controller. The main controller will immediately send its copy of the _console-config file.
Sent from controller to _console-screen HUD. The system has a new config file to send; delete the old one. This occurs whenever the _console-config notecard within the controller has a different inventory asset UUID from the last version that was sent to the console. After deleting its copy of the configuration file, the HUD will send config-q to request a replacement.
Open or close the battery hatch. Sent from controller to hatch.
The battery is in a position that should prevent the main controller's lid from closing. Upon receiving this, the controller will open the hatch if it is in a closed state, or otherwise refuse to close it.
Sent by battery hatch to battery. Ask the battery if it is in a position that would block the hatch from closing; if so, the battery should send hatch-blocked in response.
Sent by shield device to controller, describing the amount, source, and type of radiation that could not be mitigated.
Sent by main controller to shield device. Interference in the radiation bands of <type> has been received from source <id>. Mitigate what is possible, and return an interference message with the remaining impact.
SuperBit message. Displays the image or sequence named by <string>. The special string "cancel" (e.g. sign cancel) will deactivate any sign currently being displayed.