Lua Script

The Lua Script module provides a powerful, sandboxed scripting environment for custom message processing in CycBox. It enables real-time transformation, parsing, and analysis of incoming messages without requiring plugin compilation.

Key features:

• Hook functions: Intercept messages at different pipeline stages
• Multi-connection support: Single Lua instance processes messages from all connections
• Message routing: Route messages between connections dynamically
• Rich API: HTTP clients, database connections, protocol helpers, and more

Architecture

Multi-Connection Support: CycBox runs a single shared Lua task that processes messages from all connections. This enables powerful cross-connection orchestration while maintaining resource efficiency.

┌────────────────────────────────────────────────────────────────┐
│        Connection 0                Connection 1                │
│  ┌─────────┐ ┌──────────┐    ┌─────────┐ ┌──────────┐          │
│  │Transport│ │Processor │    │Transport│ │Processor │          │
│  └────┬────┘ └────┬─────┘    └────┬────┘ └────┬─────┘          │
│       │           │               │           │                │
│       └─────┬─────┘               └─────┬─────┘                │
│             │                           │                      │
│             └─────────────┬─────────────┘                      │
│                           ▼                                    │
│              ┌─────────────────────────┐                       │
│              │   Shared Lua Task       │ ← Single Lua instance │
│              │  - on_receive()         │                       │
│              │  - on_send()            │                       │
│              │  - on_send_confirm()    │                       │
│              │  - on_timer()           │                       │
│              └───────────┬─────────────┘                       │
│                          ▼                                     │
│                         UI                                     │
└────────────────────────────────────────────────────────────────┘

RX Path:
Transport → [Codec Decode] → [Transformer] → [Format] → Lua [on_receive] → UI

TX Path :
UI → Lua [on_send] → [Transformer] → [Codec Encode] → Transport
                                            ↓
                                         [Format] → Lua [on_send_confirm] → UI

Timer:
Every 100ms → [on_timer - global]

Key Features:

• Connection ID Tracking: Every message carries a connection_id field identifying its source/destination connection
• Global Timer: on_timer() runs once globally every 100ms (not per-connection)

Scripts can implement any combination of hooks to intercept and modify messages at different stages. The global message object is available in hooks for reading and modifying message data.

Quick Start

A minimal Lua script implements one or more optional hook functions:

-- Called once on startup - initialize state
function on_start()
    log("info", "Script initialized with " .. get_connection_count() .. " connections")
end

-- Called for each received message - parse and extract data
function on_receive()
    local payload = message.payload
    -- Parse payload and extract values
    message.add_int_value("temperature", parse_temp(payload))
    return true  -- Return true if message was modified
end

-- Called for each outgoing message - modify before sending
function on_send()
    -- Modify payload or route to different connection
    return false  -- Return false if message unchanged
end

-- Called every 100ms - periodic tasks
function on_timer(timestamp_ms)
    -- Schedule periodic operations
end

-- Called on shutdown - cleanup resources
function on_stop()
    log("info", "Script shutting down")
end

Key Points:

• All hooks are optional - implement only what you need
• Message hooks must return true if message was modified, false otherwise
• Global message object provides access to payload, values, and connection_id