Skip to main content

Message API

The Message object is the central data structure in CycBox's Lua scripting system. It represents a communication message flowing through the system, containing the raw data, parsed values, display formatting, and metadata.

Overview​

Messages flow through CycBox's processing pipeline:

RX: Transport → Codec → Transformer → Lua Script → UI
TX: UI → Lua Script → Transformer → Codec → Transport

In Lua scripts, you can:

  • Read and modify message payload and frame
  • Extract structured data as typed values
  • Access message metadata (timestamp, connection ID)
  • Add custom values for data visualization

Properties​

payload​

local data = message.payload  -- Get payload as bytes (Lua string)
message.payload = "\x01\x02\x03"  -- Set payload
message.payload = nil  -- Set to empty bytes

The message payload - the actual data content after protocol framing has been removed.

  • Type: Lua string (byte array)
  • Access: Read/Write
  • Nil-safe: Setting to nil clears the payload (empty bytes)

frame​

local full_frame = message.frame  -- Get full frame
message.frame = "[STX]data[ETX]"  -- Set frame
message.frame = nil  -- Set to empty bytes

The complete protocol frame including prefix, payload, suffix, and checksums.

  • Type: Lua string (byte array)
  • Access: Read/Write
  • Nil-safe: Setting to nil clears the frame (empty bytes)

timestamp​

local ts = message.timestamp  -- Get timestamp in microseconds

Message timestamp in microseconds since UNIX epoch.

  • Type: Integer (u64)
  • Access: Read-only

connection_id​

local conn_id = message.connection_id  -- Get connection ID
message.connection_id = 1  -- Set connection ID

Identifies the source/target connection (configuration index).

  • Type: Integer (u32)
  • Access: Read/Write

values_json​

local json_str = message.values_json  -- Get all values as JSON string
-- Example: '{"temperature":25.5,"humidity":60,"status":"ok"}'

Returns all message values as a JSON string for easy inspection or logging.

  • Type: String (JSON formatted)
  • Access: Read-only
  • Note: Arrays are not yet supported and will appear as null

Methods​

add_int_value()​

message:add_int_value(id, value)

Add an integer value to the message. Stored as 64-bit signed integer (Int64).

Parameters:

  • id (string, required): Unique identifier for the value (e.g., "temperature", "counter")
  • value (integer, required): Integer value to store

Example:

message:add_int_value("device_id", 1001)
message:add_int_value("counter", 42)

add_float_value()​

message:add_float_value(id, value)

Add a floating-point value to the message. Stored as 64-bit float (Float64).

Parameters:

  • id (string, required): Unique identifier for the value
  • value (number, required): Floating-point value to store

Example:

message:add_float_value("temperature", 25.5)
message:add_float_value("voltage", 3.3)
message:add_float_value("humidity", 60.2)

add_string_value()​

message:add_string_value(id, value)

Add a string value to the message.

Parameters:

  • id (string, required): Unique identifier for the value
  • value (string, required): String value to store

Example:

message:add_string_value("status", "OK")
message:add_string_value("device_name", "Sensor-01")

add_bool_value()​

message:add_bool_value(id, value)

Add a boolean value to the message.

Parameters:

  • id (string, required): Unique identifier for the value
  • value (boolean, required): Boolean value to store

Example:

message:add_bool_value("is_active", true)
message:add_bool_value("alarm", false)

get_value()​

local value = message:get_value(id)

Retrieve a value by its ID. Returns the value with its original type or nil if not found.

Parameters:

  • id (string or nil): Value identifier

Returns:

  • Integer: For Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32
  • Number: For UInt64 (if > Int64 max), Float32, Float64
  • Boolean: For Boolean values
  • String: For String values
  • nil: If ID is nil, value not found, or array types (not yet supported)

Value Storage and Visualization​

Values added to messages are:

  1. Timestamped: Each value includes the message timestamp
  2. Typed: Maintains original data type (int, float, string, bool)
  3. Visualized: Integer and float values can be plotted on charts in the UI
  4. Buffered: Recent values are kept in memory for real-time monitoring

Notes​

  • Nil Safety: payload, frame, and get_value() handle nil gracefully
  • ID Format: Value IDs should be descriptive (e.g., "temperature", "device:sensor1")
  • Type Consistency: Use the same value ID with consistent types across messages
  • Performance: Adding many values per message is efficient; values are stored compactly
  • Array Types: Array value types (Int8Array, Float32Array, etc.) are not yet supported in Lua API

See Also​