Plug-in class Reference
Available for OS7 and later
By using Plugins, you can run programs directly on the device.
This allows for advanced optimizations, such as enabling offline operations and compressing communication data, using only the obniz device itself.
Writing and Execution
Lua scripts will start immidiately on startup by OS regardless network connection status.
To write Lua scripts from obniz.js (instead of using the serial console), you can send and save a string as shown below.
Use obniz.storage.savePluginLua() to overwrite the internal flash memory. Note that this method only performs the overwrite; the changes will take effect after a reboot. To apply changes immediately, call obniz.plugin.reloadLua().
// Javascript Example
obniz.storage.savePluginLua(`
os.log("Hello World")
`);
obniz.plugin.reloadLua();
Preventing Redundant Writes
Rewriting the plugin on every connection will negatively impact the lifespan of the internal flash memory. Therefore, it is important to implement a check to skip writing if the expected Lua script is already present.
obnizOS transmits the name of the Lua script loaded at startup. You can prevent redundant writes by comparing this name. The property obniz.plugin_name contains the name of the plugin used during startup. You can specify this name within the Lua script as the return value of the plugin_name() function.
// Javascript Example
if (obniz.plugin_name !== 'my_plugin') {
console.log("Must Load Plugin");
obniz.storage.savePluginLua(`
function plugin_name()
return "my_plugin" -- max 30 chars
end
`);
obniz.plugin.reloadLua();
obniz.reboot(); // Not necessary in every case.
} else {
console.log("No Need to Load Plugin");
}
On-the-fly Execution
Lua scripts can be executed at any time via the SDK without being saved to the device's permanent storage.
// Javascript Example
obniz.plugin.execLua(`
x=1;
x=x+2;
os.log(x.."\\n")
`); // will print "3" on the obnizOS console (requires console to be enabled)
obniz.plugin.execLua(`os.log(os.getTick().."\\n")`);
obniz.plugin.execLua(`os.log(os.getTick().."\\n")`);
By using this feature, you can update necessary functions and variables on demand without rebooting the device.
This enables high-speed optimization of device behavior and maximum compression of communication traffic without incurring any downtime.
Example: Changing communication frequency from the cloud based on values
// Javascript Example
if (temperature > 26) {
obniz.plugin.execLua(`
interval = 1;
`);
} else {
obniz.plugin.execLua(`
interval = 60;
`);
}
Example: Switching the type of transmitted data based on modes
// Javascript Example
if (mode == 'temperature') {
obniz.plugin.execLua(`
function filter(data)
if data.temperature == nil then
return nil
end
return data
end
`);
} else {
obniz.plugin.execLua(`
function filter(data)
return data
end
`);
}
Total of Lua functions
-- System Event Handler
function on_event(event)
if event == "power_on" then
elseif event == "setting_mode" then
elseif event == "connecting_to_network" then
elseif event == "connecting_to_cloud" then
elseif event == "online" then
end
end
-- func(int), module(int), data(string(uint8 array))
function on_upstream(func, module, data)
if necessary then
return 1;
elseif rightnow then
return 2;
elseif mustDrop then
cloud.upstreamEnqueue(1, 2, str); -- change to differenct command
cloud.upstreamFlush(); -- optional
return 0;
end
end
-- received from obnis.js
function on_command(command)
cloud.pluginSend("123");
end
-- called while online every around 1msec
function on_online_loop()
-- os.log(\"online_loop\");
end
-- called while offline every around 1msec
-- You should care about communication because this function will be called
-- different thread.
function on_offline_loop()
-- os.log(\"offline_loop\");
end
function on_self_check()
os.log(" - self check ok");
end
function plugin_name() -- will be get by obniz.plugin_name
return "my_plugin"
end
-- Available Functions
-- OS
os.getTick(); -- system tick in msec
os.getUnix(); -- get seconds from 1970/1/1. you must adjust time by calling pingWait();
os.log("hello world");
os.wait(1000); -- 1,000msec wait
os.reboot();
os.resetOnDisconnect(false); -- It will never reset after disconnection. And queued data never lost when offline.
os.sleep(5 * 1000, 0); -- deep sleep + external module sleep.
os.sleep(5 * 1000, 1); -- deep sleep + without external module sleep.
os.sleep(5 * 1000, 2); -- light sleep + external module sleep.
os.sleep(5 * 1000, 3); -- light sleep + without external module
os.getVersion();
os.getHW();
-- storage file
storage.fileOpen("text.txt")
storage.fileWrite("ABC");
storage.fileAppend("abcdefg");
length = storage.fileGetSize();
data = storage.fileRead(0, length);
storage.fileClose();
-- storage kvs
error = storage.kvsSave({ name = "Yuki", attr = { engineer = true } })
data = storage.kvsLoad();
-- Cloud
cloud.connect();
cloud.disconnect();
cloud.upstreamEnqueue(0, 1, data) -- module func data
cloud.pluginSend(data);
cloud.pluginSendFrameStart(frame_id, length); -- framing
cloud.pluginSendFrameEnd(); -- framing
cloud.enqueueTimestampByTick(os.getTick()-1000); -- it will enqueue unix timestamp
-- io
io.retain(1, true);
io.output(1, true);
local val = io.input(1);
-- ad
local val = ad.get(1); -- 0.0v~3.3v
-- uart
uart.start(1, 2, 9600) -- tx:io1 rx:io2 baud:9600
uart.send("hello");
local data = uart.recv() -- uart.recv(1) limit to 1byte max
if #data > 1 then
os.log(data); -- received
end
-- spi
local err = spi.start(20, 21, 19, 8, 100 * 1000); -- MOSI, MISO, CLK, CS(could be null for non shared SPI), baudrate
if err > 0 then
os.log("SPI Error: " .. err);
return
end
let result = spi.write(string.char(0x40, 0x00, 0xC0)); -- result must be 3bytes if success.
-- wifi
wifi.on();
wifi.off();
wifi.sniffStart(callback);
wifi.sniffSetChannel(2);
wifi.sniffStop();
-- ble
ble.on();
ble.off();
ble.scanStart(onFind, { -- default option values
active=true,
interval=16,
window=16,
phy1m=true,
phyCoded=true,
duplicate=true
});