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](#overview)
2. [Core Architecture](#core-architecture)
3. [Device Registration](#device-registration)
4. [Command Protocol](#command-protocol)
5. [Capability System](#capability-system)
6. [Security Architecture](#security-architecture)
7. [Event System](#event-system)
8. [Backward Compatibility](#backward-compatibility)
9. [Implementation Guidelines](#implementation-guidelines)
10. [API Reference](#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
```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
```
### Data Structures
#### Device Registration Format
```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"
}
```
#### Command Format
```json
{
"version": 200,
"source": "uuid-of-sender",
"target": "uuid-of-target",
"command": "command_name",
"parameters": {
"param1": "value1",
"param2": "value2"
},
"timestamp": 1234567890,
"nonce": "unique-identifier"
}
```
---
## Device Registration
### Registration Process
```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
]));
}
```
### Device Discovery
```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);
}
```
---
## Command Protocol
### Command Creation and Sending
```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);
}
```
### Command Processing
```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);
}
```
---
## Capability System
### Capability Declaration
```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
];
```
### Capability Discovery
```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);
}
```
---
## Security Architecture
### Multi-Layer Security System
#### Layer 1: Creator Verification
```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;
}
```
#### Layer 2: Device Signature System
```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;
}
```
#### Layer 3: Capability-Based Access Control
```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;
}
```
#### Layer 4: Challenge-Response Authentication
```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;
}
```
#### Layer 5: Community Trust Network
```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
}
```
---
## Event System
### Event Broadcasting
```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);
}
```
### Event Subscription
```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);
}
}
```
---
## Backward Compatibility
### ORIX Compatibility Layer
```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
}
```
### ACS Compatibility Bridge
```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);
}
```
### KOR Compatibility Bridge
```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
}
```
---
## Implementation Guidelines
### Memory Management
```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);
}
}
```
### Error Handling
```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
}
```
### Logging and Debugging
```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);
}
```
---
## API Reference
### Core Functions
#### 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)`
### Standard Commands
#### 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
### Standard Events
#### 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.*