ORION Protocol Specification

ORION Protocol Specification v2.0

Open Robotics In Organic Networks

A modern interoperability protocol for Second Life robot systems, succeeding ORIX with contemporary LSL capabilities.

Table of Contents

1. Overview 2. Core Architecture 3. Device Registration 4. Command Protocol 5. Capability System 6. Security Architecture 7. Event System 8. Backward Compatibility 9. Implementation Guidelines 10. API Reference

Overview

Vision

ORION (Open Robotics In Organic Networks) is the evolution of ORIX, designed to succeed where ORIX failed by leveraging modern LSL capabilities (LSD, JSON) and open development principles.

Key Improvements Over ORIX

• Modern Technology Stack: LSD + JSON instead of channel-based approaches
• Persistent State: Data survives script resets and rezzing
• Granular Security: Capability-based access control vs all-or-nothing trust
• Dynamic Discovery: Real-time device capability discovery
• Open Standards: Community-driven development vs proprietary systems

Design Principles

1. Memory Efficient: Use LSD for storage, minimize script memory usage 2. UUID Targeting: Use llRegionSayTo for privacy and reliability 3. Capability Discovery: Devices advertise what they can do 4. Graceful Degradation: Fallbacks when capabilities aren't available 5. Event Persistence: LSD stores events when scripts reset 6. Backward Compatible: Bridge layers for existing systems

Core Architecture

Constants and Configuration

<source lang="lsl"> // ORION Core Protocol Constants integer ORION_VERSION = 200; // 2.0.0 integer ORION_REGISTRY_CHANNEL = -999999; // Device discovery integer ORION_COMMAND_CHANNEL = -999998; // Command execution integer ORION_EVENT_CHANNEL = -999997; // Event broadcasting

// LSD Keys for Persistent Storage string ORION_DEVICES = "orion_devices"; // Registered devices string ORION_CONFIG = "orion_config"; // System configuration string ORION_STATE = "orion_state"; // Current system state string ORION_CAPABILITIES = "orion_caps"; // Device capabilities string ORION_PERMISSIONS = "orion_permissions"; // Access permissions string ORION_TRUSTED_CREATORS = "orion_trusted_creators"; // Trusted creators string ORION_DEVICE_SIGNATURES = "orion_device_signatures"; // Device signatures string ORION_TRUST_NETWORK = "orion_trust_network"; // Community trust </source>

Data Structures

Device Registration Format

<source lang="json"> {

   "id": "uuid-of-device",
   "type": "controller|battery|accessory|core",
   "name": "Device Name",
   "owner": "uuid-of-owner",
   "capabilities": ["power_control", "rlv_relay", "charging"],
   "version": "2.0.0",
   "registered": 1234567890,
   "signature": "device-signature-hash"

} </source>

Command Format

<source lang="json"> {

   "version": 200,
   "source": "uuid-of-sender",
   "target": "uuid-of-target",
   "command": "command_name",
   "parameters": {
       "param1": "value1",
       "param2": "value2"
   },
   "timestamp": 1234567890,
   "nonce": "unique-identifier"

} </source>

Device Registration

Registration Process

<source lang="lsl"> // Device Registration register_device(string device_type, list capabilities) {

   key device_id = llGetKey();
   string device_info = llList2Json(JSON_OBJECT, [
       "id", (string)device_id,
       "type", device_type,
       "name", llGetObjectName(),
       "owner", (string)llGetOwner(),
       "capabilities", llList2Json(JSON_ARRAY, capabilities),
       "version", (string)ORION_VERSION,
       "registered", llGetUnixTime(),
       "signature", generate_device_signature()
   ]);
   
   // Store in LSD registry
   string registry = llLinksetDataRead(ORION_DEVICES);
   registry = llJsonSetValue(registry, [(string)device_id], device_info);
   llLinksetDataWrite(ORION_DEVICES, registry);
   
   // Announce to region
   llRegionSay(ORION_REGISTRY_CHANNEL, llList2Json(JSON_OBJECT, [
       "action", "register",
       "device", device_info
   ]));

} </source>

Device Discovery

<source lang="lsl"> // Find devices by type or capability list find_devices(string device_type, list required_capabilities) {

   string registry = llLinksetDataRead(ORION_DEVICES);
   list matching_devices = [];
   
   // Parse registry and find matches
   // Implementation would iterate through registered devices
   
   return matching_devices;

}

// Get device capabilities list get_device_capabilities(key device_id) {

   string registry = llLinksetDataRead(ORION_DEVICES);
   string device_info = llJsonGetValue(registry, [(string)device_id]);
   string caps_json = llJsonGetValue(device_info, ["capabilities"]);
   
   return llJson2List(caps_json);

} </source>

Command Protocol

Command Creation and Sending

<source lang="lsl"> // Create ORION command string create_orion_command(key target, string command, string params) {

   return llList2Json(JSON_OBJECT, [
       "version", ORION_VERSION,
       "source", llGetKey(),
       "target", target,
       "command", command,
       "parameters", params,
       "timestamp", llGetUnixTime(),
       "nonce", llGetKey() // Unique identifier
   ]);

}

// Send command with UUID targeting for privacy send_orion_command(key target, string command_json) {

   // Verify target supports the command
   string command = llJsonGetValue(command_json, ["command"]);
   if (!supports_command(target, command)) {
       llOwnerSay("Target device does not support: " + command);
       return;
   }
   
   // Use llRegionSayTo for privacy and reliability
   llRegionSayTo(target, ORION_COMMAND_CHANNEL, command_json);

} </source>

Command Processing

<source lang="lsl"> // Process incoming ORION command process_orion_command(string command_json) {

   key source = (key)llJsonGetValue(command_json, ["source"]);
   key target = (key)llJsonGetValue(command_json, ["target"]);
   string command = llJsonGetValue(command_json, ["command"]);
   string params = llJsonGetValue(command_json, ["parameters"]);
   integer timestamp = (integer)llJsonGetValue(command_json, ["timestamp"]);
   
   // Verify command is for this device
   if (target != llGetKey()) {
       return; // Not for us
   }
   
   // Verify sender permissions
   if (!check_permission(source, command)) {
       send_error_response(source, "Permission denied");
       return;
   }
   
   // Execute command
   string result = execute_command(command, params);
   
   // Send response
   send_orion_response(source, command, result);

} </source>

Capability System

Capability Declaration

<source lang="lsl"> // Device capabilities are declared during registration list ORION_STANDARD_CAPABILITIES = [

   "power_control",      // Can control power states
   "rlv_relay",          // Supports RLV relay functions
   "charging",           // Can charge/power other devices
   "communication",      // Can handle communication routing
   "storage",            // Provides data storage
   "sensing",            // Environmental sensing
   "movement",           // Movement control
   "accessories",        // Manages accessories
   "programming",        // Supports programming interfaces
   "monitoring"          // System monitoring and diagnostics

]; </source>

Capability Discovery

<source lang="lsl"> // Check if device supports specific capability integer device_supports_capability(key device_id, string capability) {

   list caps = get_device_capabilities(device_id);
   return llListFindList(caps, [capability]) != -1;

}

// Check if command is supported integer supports_command(key device_id, string command) {

   // Map commands to required capabilities
   string required_cap = get_command_capability_requirement(command);
   return device_supports_capability(device_id, required_cap);

} </source>

Security Architecture

= Layer 1: Creator Verification

<source lang="lsl"> verify_device_creator(key device_id) {

   key creator = llGetCreatorKey(device_id);
   string trust_data = llLinksetDataRead(ORION_TRUSTED_CREATORS);
   
   // Check if creator is trusted
   if (llJsonGetValue(trust_data, [(string)creator]) == JSON_TRUE) {
       return TRUE;
   }
   
   // Check device signature database
   string signatures = llLinksetDataRead(ORION_DEVICE_SIGNATURES);
   string device_sig = llJsonGetValue(signatures, [(string)device_id]);
   
   if (device_sig != JSON_NULL) {
       return verify_device_signature(device_id, device_sig);
   }
   
   return FALSE;

} </source>

= Layer 2: Device Signature System

<source lang="lsl"> // Generate unique device signature generate_device_signature() {

   // Hash of script content + creator + creation time
   string script_hash = llSHA1String(llGetScriptName() + llGetScriptContents());
   string signature_data = llList2Json(JSON_OBJECT, [
       "creator", llGetCreatorKey(llGetKey()),
       "created", llGetDate(),
       "script_hash", script_hash,
       "device_id", llGetKey()
   ]);
   
   // Store in ORION signature database
   string signatures = llLinksetDataRead(ORION_DEVICE_SIGNATURES);
   signatures = llJsonSetValue(signatures, [(string)llGetKey()], signature_data);
   llLinksetDataWrite(ORION_DEVICE_SIGNATURES, signatures);
   
   return signature_data;

} </source>

= Layer 3: Capability-Based Access Control

<source lang="lsl"> // Grant specific permissions to devices grant_permissions(key device_id, list permissions) {

   string permission_data = llList2Json(JSON_OBJECT, [
       "device", device_id,
       "permissions", llList2Json(JSON_ARRAY, permissions),
       "granted_by", llGetOwner(),
       "granted_time", llGetUnixTime(),
       "expires", llGetUnixTime() + 86400 // 24 hours
   ]);
   
   string perms = llLinksetDataRead(ORION_PERMISSIONS);
   perms = llJsonSetValue(perms, [(string)device_id], permission_data);
   llLinksetDataWrite(ORION_PERMISSIONS, perms);

}

// Check device permissions check_permission(key device_id, string required_permission) {

   string perms = llLinksetDataRead(ORION_PERMISSIONS);
   string device_perms = llJsonGetValue(perms, [(string)device_id]);
   
   if (device_perms == JSON_NULL) return FALSE;
   
   list permissions = llJson2List(llJsonGetValue(device_perms, ["permissions"]));
   integer expires = (integer)llJsonGetValue(device_perms, ["expires"]);
   
   // Check if permission exists and hasn't expired
   if (llListFindList(permissions, [required_permission]) != -1 && 
       expires > llGetUnixTime()) {
       return TRUE;
   }
   
   return FALSE;

} </source>

= Layer 4: Challenge-Response Authentication

<source lang="lsl"> // Generate authentication challenge string generate_challenge(key device_id) {

   string challenge = llSHA1String((string)llGetKey() + (string)llGetUnixTime());
   
   // Store challenge for this device
   string challenges = llLinksetDataRead("orion_challenges");
   challenges = llJsonSetValue(challenges, [(string)device_id], challenge);
   llLinksetDataWrite("orion_challenges", challenges);
   
   return challenge;

}

// Verify challenge response verify_response(key device_id, string response) {

   string challenges = llLinksetDataRead("orion_challenges");
   string expected_challenge = llJsonGetValue(challenges, [(string)device_id]);
   
   if (expected_challenge == JSON_NULL) return FALSE;
   
   // Verify response contains correct challenge
   string response_challenge = llJsonGetValue(response, ["challenge"]);
   
   if (response_challenge == expected_challenge) {
       // Clear challenge after successful verification
       challenges = llJsonSetValue(challenges, [(string)device_id], JSON_NULL);
       llLinksetDataWrite("orion_challenges", challenges);
       return TRUE;
   }
   
   return FALSE;

} </source>

= Layer 5: Community Trust Network

<source lang="lsl"> // Distributed trust system - devices vouch for each other add_trust_endorsement(key endorser, key endorsed_device, string endorsement) {

   string endorsement_data = llList2Json(JSON_OBJECT, [
       "endorser", endorser,
       "endorsed_device", endorsed_device,
       "endorsement", endorsement,
       "timestamp", llGetUnixTime()
   ]);
   
   string network = llLinksetDataRead(ORION_TRUST_NETWORK);
   network = llJsonSetValue(network, [(string)endorsed_device + "_" + (string)llGetUnixTime()], endorsement_data);
   llLinksetDataWrite(ORION_TRUST_NETWORK, network);

}

calculate_trust_score(key device_id) {

   string network = llLinksetDataRead(ORION_TRUST_NETWORK);
   // Count endorsements from trusted devices
   integer endorsement_count = 0;
   integer trusted_endorsements = 0;
   
   // Parse network data and calculate trust score
   // Implementation would iterate through endorsements
   
   return trusted_endorsements; // Return trust score

} </source>

Event System

Event Broadcasting

<source lang="lsl"> // Broadcast events to region broadcast_event(string event_type, string event_data) {

   string event = llList2Json(JSON_OBJECT, [
       "type", event_type,
       "source", llGetKey(),
       "data", event_data,
       "timestamp", llGetUnixTime()
   ]);
   
   // Store in LSD for persistence
   string event_log = llLinksetDataRead("orion_events");
   event_log = llJsonSetValue(event_log, [(string)llGetUnixTime()], event);
   llLinksetDataWrite("orion_events", event_log);
   
   // Broadcast to region
   llRegionSay(ORION_EVENT_CHANNEL, event);

} </source>

Event Subscription

<source lang="lsl"> // Subscribe to specific event types subscribe_to_events(list event_types) {

   string subscriptions = llLinksetDataRead("orion_subscriptions");
   subscriptions = llJsonSetValue(subscriptions, [(string)llGetKey()], llList2Json(JSON_ARRAY, event_types));
   llLinksetDataWrite("orion_subscriptions", subscriptions);

}

// Process incoming events process_orion_event(string event_json) {

   string event_type = llJsonGetValue(event_json, ["type"]);
   key source = (key)llJsonGetValue(event_json, ["source"]);
   string data = llJsonGetValue(event_json, ["data"]);
   
   // Check if we're subscribed to this event type
   string subscriptions = llLinksetDataRead("orion_subscriptions");
   list my_subs = llJson2List(llJsonGetValue(subscriptions, [(string)llGetKey()]));
   
   if (llListFindList(my_subs, [event_type]) != -1) {
       handle_event(event_type, source, data);
   }

} </source>

Backward Compatibility

ORIX Compatibility Layer

<source lang="lsl"> // Translate ORIX commands to ORION format translate_orix_to_orion(string orix_command) {

   // Parse ORIX format: *command:{params}
   list parts = llParseString2List(orix_command, [":"], []);
   string cmd = llList2String(parts, 0);
   string params = llList2String(parts, 1);
   
   // Remove * prefix
   if (llGetSubString(cmd, 0, 0) == "*") {
       cmd = llGetSubString(cmd, 1, -1);
   }
   
   // Convert to ORION format
   return create_orion_command(NULL_KEY, cmd, params);

}

// ORIX command mappings string map_orix_command_to_orion(string orix_cmd) {

   // Map ORIX commands to ORION equivalents
   if (orix_cmd == "power") return "power_control";
   if (orix_cmd == "say") return "communication_speak";
   if (orix_cmd == "menu") return "interface_menu";
   
   return orix_cmd; // Default to same name

} </source>

ACS Compatibility Bridge

<source lang="lsl"> // Bridge for ACS CCU systems bridge_acs_command(string acs_command) {

   // Parse ACS command format
   // Convert to ORION equivalent
   // Forward to appropriate device

}

// Convert ACS state changes to ORION events broadcast_acs_state_change(string state_name, string state_value) {

   string event_data = llList2Json(JSON_OBJECT, [
       "state", state_name,
       "value", state_value,
       "source_system", "ACS"
   ]);
   
   broadcast_event("state_change", event_data);

} </source>

KOR Compatibility Bridge

<source lang="lsl"> // Bridge for KOR Controller systems bridge_kor_command(string kor_command) {

   // Parse KOR command format (!command)
   // Convert to ORION equivalent
   // Forward to appropriate device

}

// Handle KOR API requests handle_kor_api_request(string request_json) {

   // Convert KOR JSON to ORION format
   // Process through ORION system
   // Return response in KOR format

} </source>

Implementation Guidelines

Memory Management

<source lang="lsl"> // Efficient state management with LSD string get_device_state(string state_key) {

   // Check LSD first (persistent)
   string lsd_data = llLinksetDataRead("state_" + state_key);
   if (lsd_data != "") {
       return lsd_data;
   }
   
   // Fallback to script memory (temporary)
   return gActiveState;

}

// Store state efficiently void set_device_state(string state_key, string state_data) {

   // Only store if different (avoid unnecessary writes)
   string current = llLinksetDataRead("state_" + state_key);
   if (current != state_data) {
       llLinksetDataWrite("state_" + state_key, state_data);
   }

} </source>

Error Handling

<source lang="lsl"> // Standardized error responses send_error_response(key target, string error_message) {

   string error = llList2Json(JSON_OBJECT, [
       "status", "error",
       "message", error_message,
       "timestamp", llGetUnixTime()
   ]);
   
   llRegionSayTo(target, ORION_COMMAND_CHANNEL, error);

}

// Command validation integer validate_command(string command, string params) {

   // Check command exists
   // Validate parameters
   // Check permissions
   // Return TRUE if valid

} </source>

Logging and Debugging

<source lang="lsl"> // Centralized logging log_orion_event(string level, string message) {

   string log_entry = llList2Json(JSON_OBJECT, [
       "level", level,
       "message", message,
       "timestamp", llGetUnixTime(),
       "device", llGetKey()
   ]);
   
   string logs = llLinksetDataRead("orion_logs");
   logs = llJsonSetValue(logs, [(string)llGetUnixTime()], log_entry);
   llLinksetDataWrite("orion_logs", logs);

} </source>

API Reference

= Device Management

• register_device(string device_type, list capabilities)
• unregister_device(key device_id)
• find_devices(string device_type, list required_capabilities)
• get_device_capabilities(key device_id)

= Command Processing

• create_orion_command(key target, string command, string params)
• send_orion_command(key target, string command_json)
• process_orion_command(string command_json)

= Security

• verify_device_creator(key device_id)
• grant_permissions(key device_id, list permissions)
• check_permission(key device_id, string required_permission)
• generate_challenge(key device_id)
• verify_response(key device_id, string response)

= Event System

• broadcast_event(string event_type, string event_data)
• subscribe_to_events(list event_types)
• process_orion_event(string event_json)

= System Commands

• boot - Start system
• shutdown - Stop system
• restart - Restart system
• status - Get system status

= Power Management

• power_set - Set power level
• power_get - Get power level
• charge_start - Begin charging
• charge_stop - Stop charging

= Communication

• comm_speak - Speak message
• comm_whisper - Whisper message
• comm_shout - Shout message
• comm_think - Think message

= Interface

• interface_menu - Show menu
• interface_hud - Update HUD
• interface_dialog - Show dialog

= RLV Integration

• rlv_relay - RLV relay control
• rlv_restrict - Apply restrictions
• rlv_release - Release restrictions

= System Events

• system_boot - System started
• system_shutdown - System stopped
• system_error - System error

= Power Events

• power_change - Power level changed
• charge_start - Charging began
• charge_complete - Charging finished
• power_critical - Critical power level

= Communication Events

• message_received - Message received
• command_executed - Command executed
• permission_denied - Permission denied

= State Events

• state_change - Device state changed
• capability_added - Capability added
• capability_removed - Capability removed

Implementation Checklist

Required for ORION Compliance

• [ ] Device registration system
• [ ] Command processing with JSON
• [ ] Capability discovery and declaration
• [ ] Multi-layer security implementation
• [ ] Event broadcasting and subscription
• [ ] LSD-based persistent storage
• [ ] Error handling and logging
• [ ] Backward compatibility bridges

Optional for Enhanced Compatibility

• [ ] ORIX command translation
• [ ] ACS state bridging
• [ ] KOR API compatibility
• [ ] Community trust network participation
• [ ] Advanced debugging interfaces

Version History

v2.0.0 - Current

• Complete rewrite using LSD and JSON
• Multi-layer security architecture
• Capability-based access control
• Event persistence and subscription
• Backward compatibility layers

v1.0.0 - ORIX (Reference)

• Channel-based communication
• Trust script security model
• Limited device discovery
• No persistent storage

---

This specification is a living document. Contributions and feedback are welcome from the Second Life robotics community.