Lua Script API Reference

CycBox runs Lua scripts to process messages across connections (serial, TCP, WebSocket, MQTT, UDP). Scripts interact with the engine through hook functions and global APIs.

Hook Functions

All hooks are optional. Implement only what you need.

on_start()

Called once when the Lua task starts or reload, before processing any messages.

on_receive() → boolean

Called for each received message (RX path). The global message object contains the received data with connection_id identifying the source.

Return true if message was modified, false otherwise.

on_send() → boolean

Called for each outgoing message from UI (TX path, before encoder). The global message object contains the outgoing data with connection_id controlling the destination.

Return true if message was modified, false otherwise.

on_send_confirm() → boolean

Called after a successful send (TX confirmation). The global message object contains the confirmed message.

Return true if message was modified, false otherwise.

on_timer(timestamp_ms)

Called every 100ms. timestamp_ms is the current Unix timestamp in milliseconds.

on_stop()

Called before the engine stops or before script hot-reload. On hot-reload, on_stop() runs on the old script before on_start() on the new one.

Processing Pipeline

Startup:    on_start() → [ready]
RX:         Transport → Decoder → Transformer → on_receive() → UI
TX:         UI → on_send() → Transformer → Encoder → Transport → on_send_confirm() → UI
Timer:      [every 100ms] → on_timer(timestamp_ms)
Shutdown:   on_stop() → [done]

Message Object

The global message object is available in on_receive(), on_send(), and on_send_confirm().

Properties

Property	Type	Access	Description
payload	string (byte array)	Read/Write	Pure data content after protocol framing removed. Setting nil clears it.
frame	string (byte array)	Read/Write	Complete wire format including all protocol overhead. Setting nil clears it.
timestamp	integer (u64)	Read/Write	Microseconds since UNIX epoch.
checksum_valid	boolean	Read-only	Whether the frame checksum is valid. Defaults to true if no checksum metadata exists.
connection_id	integer (u32)	Read/Write	Source/target connection (0-based configuration index).
message_type	string	Read/Write	Message type: "rx", "tx", "log", "event", "request", or "response".
payload_type	string	Read-only	Payload type: "binary", "text", "mqtt", "websocket_binary", "websocket_text", etc.
highlighted	boolean	Read/Write	Whether the message is highlighted in the UI.
display_hex	boolean	Read/Write	Whether the message displays the hex dump view in the UI.
values_json	string (JSON)	Read-only	All message values as JSON. Arrays appear as null (not yet supported).

• payload is what you parse in on_receive() and build in on_send(). Protocol headers, checksums, and delimiters are stripped.
• frame is the raw bytes on the wire, including all protocol overhead.

Methods

Adding Values

Method	Parameters	Description
add_int_value(id, value [, timestamp_us])	id: string, value: integer, timestamp_us: integer (optional, µs since epoch)	Add a 64-bit signed integer value. If timestamp_us is omitted, the message timestamp is used.
add_float_value(id, value [, timestamp_us])	id: string, value: number, timestamp_us: integer (optional, µs since epoch)	Add a 64-bit float value. If timestamp_us is omitted, the message timestamp is used.
add_string_value(id, value [, timestamp_us])	id: string, value: string, timestamp_us: integer (optional, µs since epoch)	Add a string value. If timestamp_us is omitted, the message timestamp is used.
add_bool_value(id, value [, timestamp_us])	id: string, value: boolean, timestamp_us: integer (optional, µs since epoch)	Add a boolean value. Follows Lua truthiness: only nil and false are falsy.

Querying Values

Method	Parameters	Description
get_value(id)	id: string or nil	Returns value with original type, or nil if not found. Integer/float values can be visualized on charts.
get_metadata(id)	id: string or nil	Returns metadata value by id (e.g., MQTT topic, QoS), or nil if not found.
has_value(id)	id: string	Returns true if a value with the given id exists, false otherwise.
value_ids()	none	Returns a table (array) of all value id strings.

Removing Values

Method	Parameters	Description
remove_value(id)	id: string	Removes all values with the given id. Returns true if any were removed.
clear_values()	none	Removes all values from the message.

Global Functions

Connection Query

Function	Parameters	Returns
get_connection_count()	none	number — total active connections
get_transport(connection_id)	connection_id: 0-based index	string — "serial", "tcp_client", "websocket_client", "mqtt", "udp"
get_codec(connection_id)	connection_id: 0-based index	string — "modbus_rtu", "modbus_tcp", "line", "frame", "passthrough"

Utility

Function	Parameters	Returns
log(level, message)	level: "debug"/"info"/"warn"/"error" (default "info"); message: string	nothing
get_env(var_name)	var_name: string	string value or nil if not set
send_after(payload, delay_ms, connection_id)	payload: binary string (required); delay_ms: number; connection_id: 0-based (default 0)	true on success, false on failure

Binary Data Reading Functions

All reading functions take (payload, offset) where payload is a binary string and offset is 1-based (Lua convention).

Integer Readers

Function	Returns
read_u8(payload, offset)	unsigned 8-bit (0–255)
read_i8(payload, offset)	signed 8-bit (-128–127)
read_u16_be(payload, offset)	unsigned 16-bit big-endian
read_u16_le(payload, offset)	unsigned 16-bit little-endian
read_i16_be(payload, offset)	signed 16-bit big-endian
read_i16_le(payload, offset)	signed 16-bit little-endian
read_u32_be(payload, offset)	unsigned 32-bit big-endian
read_u32_le(payload, offset)	unsigned 32-bit little-endian
read_i32_be(payload, offset)	signed 32-bit big-endian
read_i32_le(payload, offset)	signed 32-bit little-endian

Float Readers

Function	Returns
read_float_be(payload, offset)	32-bit float big-endian (IEEE 754)
read_float_le(payload, offset)	32-bit float little-endian (IEEE 754)
read_double_be(payload, offset)	64-bit double big-endian (IEEE 754)
read_double_le(payload, offset)	64-bit double little-endian (IEEE 754)