LSL Protocol/Restrained Love Open Relay Group/ORG Requirements

STATUS: draft

VERSION: 0001

Definition of an ORG device

A RLVR device is compliant with ORG specifications version 0001 if

it implements Marine Kelley's RLVR protocol version 1.100
it implements the !x-orgversions meta-command as defined below
it implements the protocol fixes below
all metacommands it supports are of the following types:

meta-commands in RLVR protocol, behaving as described in RLVR specifications
meta-commands, whose names start with "!x-", behaving as described in ORG specifications
proprietary or experimental metacommands, whose names start with "!_-" (replace "_" by any letter that is not "x)

!x-orgversions

This meta-command purpose it twofold. First it gives the list of supported ORG x-tensions, second it is similar to !version in RLVR protocol, as it gives the version of ORG core specification and ORG x-tensions that are implemented.

C<->R
  ->   query,rUUID,!x-orgversions
 <-    query,cUUID,!x-orgversions,ORG=0001/who=001/email=005

The acknowledgement string of the relay is a list separated by "/" whose items are of the form <package>=<version>. The first package is "ORG", the core specification of ORG relays, its version string is the version of the specification (4 digits). The other packages are ORG x-tension names (not meta-command names, as one x-tension can require several metacommands, thus the name does not include the prefix "!x-"), whose version string is 3 digits.

The support of this metacommand is mandatory for an ORG relay. It is also required that the list of packages in the !x-orgversions reply includes the package "ORG" and the exact list of supported optional x-tensions.

ORG RLVR fixes

Preliminaries/Reminders

RLVR device message grammar:

<r_msg> ::= IDENT','KEY','<command>','ACK;
<d_msg> ::= IDENT','KEY','<commands>;
<commands> ::= <command> | <command>'|'<commands>;
<command> ::= <rlvcommand> | <metacommand>;
<rlvcommand> ::= '@'RLVCOMMAND;
<metacommand> ::= '!'METACOMMANDNAME<metacommandarguments>;
<metacommandarguments> ::=  | '/'ARG<metacommandarguments>;

Tokens:

IDENT: any string without ","
KEY: any UUID
ACK: any string without ","
RLVCOMMAND: any string without ","
METACOMMANDNAME: any string without "/" and ","
ARG: any string without "/" and ","

Definitions:

The following actions are considered "locking" a relay:

a restricting command followed by a "ok" acknowledgement
a ping/pong exchange with this relay

The following actions are considered "unlocking" a relay:

the relay and controlling devices go out of shout range of each other
the relay sends "release,KEY,!release,ok"
the controlling device sends a !release

General Relay requirements

A relay should not send anything on RLVR channel that is not a valid <r_msg>. A relay should check periodically (every few minutes), that every device that locks it is still within shout range. If not, every restriction from the device should be released. If <d_msg> is not a ","-list of 3 items, then the relay should ignore it, else, for every <command> in a received <d_msg>,

if the <command> is a <rlvcommand>, the relay MUST acknowledge it, either by "ok", and transmit the command as such to the viewer with llOwnerSay("@"+RLVCOMMAND), or by "ko" and not transmit it.
if the <command> is a <metacommand>

if the METACOMMANDNAME is unknown, the relay MUST acknowledge by "ko"
else if the relay knows the METACOMMANDNAME it receives with n arguments and the known definition can accept m1, m2, ... arguments, then

if n is smaller than every mi, the relay should acknowledge by "ko" and not execute it
else the relay should only consider the mj first arguments where mj is the biggest mi smaller or equal than n, and do whatever the definition tells to do when there are mj arguments (ignoring the possible subsequent ones). If the definition implies no acknowledgement, then the relay should acknowledge by "ok".

if the <command> is neither, then the relay should ignore it (no acknowledgement whatsoever)

!ping/!pong? Is it ok to have pong not acknowledged?

General controlling device requirements

A controlling device MUST not send anything on RLVR channel that is not a valid <d_msg>.
A controlling device MUST, at any time when a relay is locked, provide a mechanism that will unlock it in bounded time. (i.e.: either there is a menu that will release the victim, or there is a timer, or a menu should be able to start such a timer). At least one person MUST know what this mechanism is, and if it requires an action from someone else, be able to tell that other person what s/he has to do.