light bus

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.

bolts on|off
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.
broken|fixed
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.
carrier <device> <key>
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".
charge start|stop
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.
color <r> <g> <b>
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.
device <device> <key>
There is a device at address <device> with the key <key>. This is only sent to the HUD, either in response to a device addition or in bulk when the HUD is installed.
fan <level>
The current fan speed, measured from 0 to 100.
follow <target>
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.
freeze|unfreeze
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.
interference-state <type>
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.

classeffects
MImpairment of motor control
CImpairment of cortex operation
SImpairment of sound (speech) output
NImpairment of sensory functions
YImpairment 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.
name <name>
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.
on|off
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.
persona <name>
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.
power <level>
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.
rate <amount>
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> 0|1
Subsystem <SS> is either on (1) or off (0), where <SS> is a numeric value indicating:

subsystemnumeric value
VIDEO1
AUDIO2
MOVE4
TELEPORT8
RAPID16
VOICE32
MIND64
PREAMP128
POWER_AMP256
RADIO_IN512
RADIO_OUT1024
GPS2048
IDENTIFY4096

These values were changed in Companion 8.4 to be more consistent. See practical breakdown here.
wait-teleport <time>
The FTL subsystem is refreshing, and the unit will be unable to teleport for <time> more seconds. Sent every second.
working|done
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)

add <device>
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.
add-command <command>
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.
auth <device> <key>
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.
auth-compare <device> <user1> <user2>
Modified version of auth. Checks if <user2> is at least <user1>'s rank, and if so, sends accept to the device for <user2>. This allows decisions about whether or not <user2> has the right to pre-empt <user1>, for example when grabbing a leash.
carrier <device> <key>
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.
carrier-q
Instructs the controller to send carrier.
color-q
Instructs the controller to send color.
devices
Instructs the controller to send a list of connected devices (using multiple device 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.
follow-q
Sends the follow message.
internal <device> <number> <key> <message>
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.
load <device> <task> <W>
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.'
persona-q
Instructs the controller to send persona.
port <type> <key>
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:

class
power
audio-in
audio-out
data-1
data-2
port-connect <type>
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:
  1. 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.
  2. 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.
If the request needs to be forwarded to a port host (the first case), then the host is guaranteed to provide a port-real message.
port-disconnect <type>
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.
power-q
Instructs the controller to send on or off as appropriate. It will also send bolts.
remove <device>
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.
subsystem-q <subsystem>
Checks if <subsystem> is enabled, and reports back to the device with the subsystem message. See table at subsystem for parameter format. Note: before Companion 8.5m3, the parameter was ignored, so this command could only return the unit's video (0) status.
version <device> <version> <PIN>
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.

active (MC to device)

policy <name> <state>: 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>.

port <type> <key>: The key indicated can provide port functionality of the indicated type. Repeat request to key.

port-real <type> <key>: Send particles to this key.

port-connect <type>: Something is connecting to the device that receives this message. Trigger connect effects.

port-disconnect <type>: Something is disconnecting from the device that receives this message. Trigger disconnect effects.

command <user key> <command> <parameters>: the user has typed @command parameters; handle accordingly

probe: soliciting devices to add to bus

accept <key>: Yes, <key> has permission to operate the unit.

session-ready <key> <session-number>: sxdwm (exhibition 4) session <session-number> has been created for <key>.

add-confirm: installation successful, proceed

add-fail: installation unsuccessful (usually caused by another device in the same slot or refusal of a foreign connection)

remove-confirm: uninstallation successful, proceed

remove-fail: uninstallation not successful, don't proceed (e.g. removing a battery while the power is on)

device-to-device messages

port-real <type> <key>: Send cable particles to this key.

port-connect <type>: Something is connecting to the device that receives this message. Trigger connect effects.

port-disconnect <type>: Something is disconnecting from the device that receives this message. Trigger disconnect effects.

connected <device>: Device is connected. (Optional)

disconnected <device>: Device is disconnected. (Optional)

reconnected <device>: Device is reconnected. (Optional)

device-specific active messages

sign <string> (MC to superbit): display the specified image or loop.

hatch-blocked-q (MC to battery): ask the battery if the hatch is blocked; force open if hatch-blocked is sent

hatch-blocked (battery to MC): the hatch is blocked; force it open

hatch open (MC to hatch): open the hatch

hatch close (MC to hatch): close the hatch

config-update (MC to HUD): the system has a new config file to send; delete the old one

config-q (HUD to MC): please send config file if available

shield <duration> <intensity> <id> <type> (MC to shield): interference received; attempt to mitigate

interference <type> <intensity> <duration> <source_key> (shield to MC): apply specified interference; shield was not able to block