Berry scripting for various IoT platforms - tutorial for OBK new script integration part 1

Berry is a lightweight scripting language designed for embedded system. It features dynamically typed, one-pass compiler and interpreter with core’s code size is less than 40KiB which can run on less than 4KiB heap. Thanks to latest OBK integration, Berry can now run on most of new IoT modules, including BK7231, W800/W600, ESP32, BL602, LN882, Realtek. It can also run in OBK Windows simulator, so you can try out Berry easily, along with full MQTT and Home Assistant integration.

For more information about Berry, please see Berry documentation:
https://berry.readthedocs.io/en/latest/index.html

Now let's focus on running Berry in OBK. Currently, there are two options:
Option 1: you can just use OpenBeken Simulator to try Berry on Windows, just get binaries here: https://github.com/openshwprojects/OpenBK7231T_App/releases

Option 2: You can use only builds (no toolchain required) to enable Berry for the platform of your choice, follow this tutorial. Keep in mind that on some platforms you might need to disable some other features in order to keep binary size small enough to run. This is because OBK comes by default with most of the features enabled, so each binary has TuyaMCU driver, LED driver, WS2812 driver with animations, and even Tasmota JSON support, and you most likely will not this kind of thing. So, edit obk_config.h to suit your needs. Just remember - for Berry, you need to enable ENABLE_OBK_BERRY define.
Futhermore, the stack sizes may not be adjusted for Berry currently, so you might need to increase them on your own. There is also still room for optimization in Berry code, for example, some event handlers could be more or less delayed to avoid large stack requirement. This is still subject to change in future.

This tutorial will be based on OBK Windows Simulator, so anyone can run it, even with no IoT devices.

Don't forget to get OBK simulator samples here:
https://github.com/openshwprojects/obkSimulator
They will be used here for demonstration purposes.

I also assume that you know more or less how to run OBK Simulator - it creates a simulation window and virtual device page on your local IP, port 80. For more information, see related Simulator topic.

First Berry steps
Let's start by executing some simple Berry commands in OBK command line:


The same could be done in the Web App console:

This way you can test various berry commands, for example, expressions:



First Berry commands
The most simple way to call OBK commands from Berry is "runCmd" command.
Commands should be taken from here:
https://github.com/openshwprojects/OpenBK7231T_App/blob/main/docs/commands.md
For example, you call setChannel from Berry to set new channel value. In OBK, this can for example set relay state, along with whole MQTT publish and state update:


You can use the same approach to run text commands as well:

Similary, you can use OBK publish commands to publish your data to Home Assistant:


Berry script files
Main Berry scripts should reside within Berry modules. Berry modules can be created in LittleFS file system:

Let's start by making simplest module. Call it autoexec.be. It will run on each device startup.


For faster prototyping, you can use "Save, Reset SVM and run file" button. This will also attempt to clear device state to simulate a reboot, but may not be always reliable.



Script execution over time
OBK features two commands that allows you to run scripts over time:
- setTimeout - runs commands once
- setInterval - runs command repeatedly
With setInterval, you can make a simple "blink LED" (or a relay, or anything) demo:


The same could be done with setTimeout, if needed:



Reacting to events - buttons
Berry can react to OpenBeken events. For example, you can use it with Btn_ScriptOnly button. Set a Btn_ScriptOnly role for given pin, let's say, 14, and try following code:

For the demonstration purposes, I've put two relays ("bulbs") on channel 1 and channel 2:


Reacting to events - channels
Similar approach can be taken to, for example, turn off relay after some time. In this case, we'll catch the situation when channel becomes 1 and set it back to 0 after some time. Keep in mind that for this demo I've set back the PWM2 pin button role to Btn, so it has automatic interaction with channel 1. So, channel 1 toggle is handled by OBK internally, as usual.


The code could be simplified by adding inline functions:

and even futher:


Stopping and running intervals
setInterval returns a handle that can be later used to stop the interval. You can store it in a global variable and call "cancel" later. The following example demonstrates a stoppable setInterval demo where first button press starts then interval that blinks LEDs, and second button press stops it.




Calling module functions from outside
Keep in mind that you can simply use Berry modules anywhere inside OBK. Let's consider simplified version of mentioned module:

Once you have it in LFS, you can just run OBK command:

and it will correctly toggle the blink interval.



Direct command handlers
There are more ways to call Berry functions from outside. For example, you can just create your own command handler in Berry:

Keep in mind that now you can run this command from anywhere - even from MQTT!



Direct command arguments
Commands can have arguments that are also passed to Berry. Arguments are strings by default, so you need to cast them to int to use them as a number. In this example, we'll modify the blinking command to include single argument, which is a blink interval. In order to convert it to string, I've used int(del) function.

The usage is very simple:

Of course, when in doubt, you can just print out some debug information:




Showing information on state section
OpenBeken features a main page with a state section that is automatically refreshed in background.



Interval ID will be 0 when it's inactive.




Access to OBK variables - power metering
OpenBeken has some legacy variables that were used before Berry introduction. They can be seen here:
https://github.com/openshwprojects/OpenBK7231T_App/blob/main/docs/constants.md
In Berry, you can access them with getVar function.
Here's a simple BL0942/BL0937 readout demo:


Values are correctly displayed on the main page:

Following example can be expanded with conditionals. You can use if block to check voltage value.

Now, let's set voltage to 260 and see what happens:

The error message is displayed correctly:


Extra sample - refresh counter
Following script will counter the number of automatic refreshes done by OBK state page segment:





Extra sample - loop logic and power check
The following sample was requested several times by users. This is a simple mechanism used to turn off relay when power consumption is below given threshold for given time. This can be used to detect when charging is finished.
In order to implement it, I've created a simple repeating interval called "my Logic", where I access current power value and compare it against predefined threshold, in this case, 1W. If it's below 1W, I count the number of loops, and if it reaches 5 (5 seconds, because one loop is one second here) I turn off the relay.

The following sample can be extended by, for example, moving constants to text fields:

Result:


Access to OBK variables - time variables
First start NTP driver. Once it's running, you will be able to access current time data:

Try following script:

It will print NTP hour/minute on the main panel:




Custom HTML fields
HTTP callback also allows you to create custom HTML fields. They can store any kind of data that is later processed by Berry. You can use getVar to access GET variables as well. The input field, however, can be tricky. This is becaue state section is refreshed automatically, so you'd lose the data you type. That's why there is another callback - called "prestate" that runs before state div. So field is created in prestate, and display in the state.




Related reading
For more information on OBK events (button handling, etc), clock events (NTP, etc), see autoexec.bat samples. They are not in Berry, but they can still give some insights into OBK possibilities:
https://github.com/openshwprojects/OpenBK7231T_App/blob/main/docs/autoexecExamples.md

That's all for now
This is how you can create more advanced scripts in OBK. Let me know if you have any futher suggestions or ideas.
Soon I will post tutorial part 2, which will cover more advenced HTTP stuff, TuyaMCU integration and data processing.
Just please keep in mind that Berry integration has been so far mostly tested with self tests ( https://www.elektroda.com/rtvforum/topic4109775.html ) and in Simulator, so any testing is welcome. Let me know if you try to run some of my scripts on physical devices! Any testers available - @divadiow maybe? And special thanks for @niterian for initial Berry demo.