Skip to content

rule-engine.md

Latest commit

 

History

History
122 lines (96 loc) · 3.89 KB

rule-engine.md

File metadata and controls

122 lines (96 loc) · 3.89 KB

Edge Rule Engine (Lua/JavaScript)

ComX-Bridge embeds a lightweight script engine to provide the capability to process data in real-time at the Edge before sending it to the cloud or upstream systems.

1. Overview

  • Purpose: Beyond simple data collection, perform filtering, transformation, and conditional control.
  • Languages:
    • Lua 5.1 (via gopher-lua) - Fast and lightweight, optimized for embedded environments.
    • JavaScript (via goja) - Supports ES5+, familiar to web developers.
  • Location: Executed within the Receive Loop of each Gateway.

Tip

AI-Powered Generation: You can use the AI Engine to automatically generate Lua parsing scripts for binary protocols. See AI Engine Documentation.

2. Lua Script

2-1. Configuration (config.yaml)

Specify the rule_script path in the gateway configuration.

gateways:
  - name: "sensor-gw"
    transport: { ... }
    protocol: { ... }
    rule_script: "./rules/filter_noise.lua" # Lua script path

2-2. Writing the Script (Lua)

You must define the on_message function. This function is called whenever a message is received.

-- on_message(gateway_name, raw_data_string)
-- return: modified data (string) or nil (drop)

function on_message(gateway, data)
    -- 1. Logging
    print("Received from " .. gateway .. ": " .. data)

    -- 2. Filtering (Ignore if specific string is present)
    if string.find(data, "NOISE") then
        return nil -- Drop message (do not send)
    end

    -- 3. Data Transformation (Add Header)
    local new_data = "[PROCESSED] " .. data

    return new_data
end

2-3. Auto-Generated Parser Example

If you use the AI Engine to analyze a binary protocol, it can generate a script like this:

-- Generated by ComX-Bridge AI
function on_message(gateway, data)
    -- Parse Binary Structure
    local header = string.sub(data, 1, 2)
    local payload = string.sub(data, 3, 10)
    
    -- Convert to JSON for Cloud
    return string.format('{"header":"%s", "payload":"%s"}', header, payload)
end

3. JavaScript Script

3-1. Configuration (config.yaml)

If you use the .js extension, the JavaScript engine is automatically selected.

gateways:
  - name: "iot-gw"
    transport: { ... }
    protocol: { ... }
    rule_script: "./rules/transform.js" # JavaScript script

3-2. Writing the Script (JavaScript)

Define the on_message function just like in Lua.

// on_message(gateway, data)
// return: modified data (string/object) or null/undefined (drop)

function on_message(gateway, data) {
    // 1. Logging
    console.log("Received from " + gateway + ": " + data);

    // 2. JSON Parsing and Transformation
    try {
        var obj = JSON.parse(data);
        obj.processed = true;
        obj.timestamp = Date.now();
        return JSON.stringify(obj);
    } catch (e) {
        // Return original if not JSON
        return data;
    }
}

3-3. Built-in Functions

Built-in functions available in the JavaScript engine:

Function Description
console.log(msg) Print Log
console.warn(msg) Print Warning
console.error(msg) Print Error
JSON.parse(str) Parse JSON string
JSON.stringify(obj) Convert object to JSON string
hexToBytes(hex) Convert Hex string to Byte array
bytesToHex(bytes) Convert Byte array to Hex string

4. Use Cases

  • Noise Filtering: Reduce network costs by removing meaningless dummy data or error packets in advance.
  • Unit Conversion: Convert Celsius to Fahrenheit, or scale Raw values to physical quantities.
  • Format Normalization: Unify data formats from different devices into JSON or specific structures.
  • Threshold-based Alarms: Send to a separate alarm channel if specific values exceed thresholds.
  • Protocol Conversion: Convert legacy protocols to modern JSON/REST formats.