Transaction

Available for OS7.1.0 and later

A transaction is a request that waits for a reply. With obniz.plugin.send() and cloud.pluginSend(), data only flows one way. With transactions, obniz.js and the Lua plugin can ask each other and get an answer back.

The two can be combined: a script run by callWait() can ask obniz.js a question with cloud.transactionWait() while it runs.

obniz.plugin.callWait(lua_script, timeout)

Runs a Lua script on the device and waits for its return value. While execLua() only sends a script, callWait() resolves with what the script returns.

Returns a Promise.

• Resolved with the first value the script returns, as a string. A number is converted to a string. Other values, such as tables, booleans, and nil, are resolved as an empty string, so convert them to a string (for example, JSON) before returning.
• Rejected when the script raises an error (with the Lua error message), when the timeout elapses, or when the connection to the device is reset.

The script runs in the same Lua environment as the plugin, so it can read and change the plugin's global variables and call its functions.

// Run Lua and wait for its return value
const result = await obniz.plugin.callWait(`return "hello from lua"`);
console.log(result); // "hello from lua"

// Read a value from the running plugin
const count = await obniz.plugin.callWait(`return tostring(counter)`);

// An error raised in Lua rejects the Promise
try {
  await obniz.plugin.callWait(`MUST FAILED`);
} catch (e) {
  console.log("lua error:", e.message);
}

The device can run up to 100 callWait() scripts at the same time (including scripts waiting in cloud.transactionWait()). Beyond that, the Promise is rejected with busy.

cloud.transactionWait(data, callback, timeout_ms)

Sends data from the Lua plugin to obniz.js and waits for the reply.

The callback can be omitted. cloud.transactionWait(data, timeout_ms) is also accepted.

Where it can be called

cloud.transactionWait() suspends the running Lua code until the reply arrives. This is only possible inside a script run by obniz.plugin.callWait().

When it is called elsewhere, such as in on_online_loop(), on_command(), or the plugin loaded at startup, it does not wait and immediately returns false, nil.

While one script waits, the rest of the plugin keeps running: on_online_loop() and the other handlers continue to be called. A reply that arrives after the timeout is ignored.

-- Run inside obniz.plugin.callWait()
local success, result = cloud.transactionWait("get_config", 5000)
if success then
  threshold = tonumber(result)
  return "updated"
else
  return "failed"
end

obniz.plugin.onCloudTransaction

The handler that answers cloud.transactionWait() on the obniz.js side.

obniz.plugin.onCloudTransaction = async (data, str) => {
  // data: number[] (raw bytes), str: the same data as a string
  return "reply";
};

• The handler can be an async function. The reply is sent when the returned Promise settles.
• Return a string, a byte array (number[]), or a Buffer. Returning nothing sends an empty string.
• Throwing an error (or rejecting) reports success = false to Lua, with the error message as result.
• If no handler is set, obniz.js replies with success = false immediately, so Lua does not wait until the timeout.

Example: Asking the cloud from the device

In this example, obniz.js runs a script on the device. The script asks obniz.js for a setting value, applies it, and returns the result.

// Answer the question from the plugin
obniz.plugin.onCloudTransaction = async (data, str) => {
  if (str === "get_interval") {
    // For example, read the value from your database or another API here.
    return "60000";
  }
  throw new Error(`unknown request: ${str}`);
};

// Run a script that asks the question and waits for the answer
const result = await obniz.plugin.callWait(`
  local success, value = cloud.transactionWait("get_interval", 5000)
  if not success then
    return "failed: " .. tostring(value)
  end
  interval = tonumber(value)
  return "interval=" .. value
`);
console.log(result); // "interval=60000"