How to create a custom driver for OpenBeken with online builds (no toolchain required)

Here I will show you how you can create a custom OpenBeken driver. Custom OpenBeken driver can implement almost any logic you want and runs directly on OBK device. You don't need to setup toolchain for that, builds can be done online. Writing a custom OBK driver does not require much programming knowledge, it can be done with the really basic, basic skillset. Writing OBK driver directly is also much more flexible than scripting and gives you a better control over device. Futhermore, I can always help with that, so let's check out how it can be done.

This short guide was created for users asking how to add custom features to OpenBeken. I hope it will give you a basic overview of the procedure.

1. Preparing workflow
Ok, so first go to our repository on Github:
https://github.com/openshwprojects/OpenBK7231T_App

Make a fork and open a pull request like you would usually do. It's easiest to do it with Github gui. If you are not sure how, check the Git documentation and tutorials.

This will allow you to get online builds in PRs:
https://github.com/openshwprojects/OpenBK7231T_App/pulls
Once your PR is accepted, you will be able to get binaries for all platforms as described in:
OpenBeken online building system - compiling firmware for all platforms (BK7231, BL602, W800, etc)

2. Preprocessor define for a driver
All drivers should have a #define in obk_config.h:
https://github.com/openshwprojects/OpenBK7231T_App/blob/main/src/obk_config.h
This allows us to turn them on and off for each platform.
Let's create a define for our driver. Let's say that I will be developing it on Windows Simulator for now. So, in the #ifdef WINDOWS section, let's add our own new define:

Our diff so far:



3. Main drivers table entry
Now let's modify drv_main.c:
https://github.com/openshwprojects/OpenBK7231T_App/blob/main/src/driver/drv_main.c
We need to add an entry to drivers array. Whole entry should be in preprocessor block. We also need to fill the documentation entries.

A driver has:
- name
- init function
- every second update function
- quick tick update function
- http index display function
- and some other less often used functions, like shutdown function or channel change callback.
So next we can create those function in separate new file and add their declarations to drv_local.h

4. New driver file
So let's create a drv_sample_ntpSwitch.c stub:

We can also add some display to know whether our driver really works:

Let's build and flash firmware for our chosen platform and try starting the driver:

You should get "OK" reply:

You should also get text on main panel:


5. What can be done in drivers?
Basically everything can be done in drivers, but some more specific operations may require code injection outside your driver file. Still, for the start, let's do something simple. Like the user request we had recently:

Quote:

Switch the NTP server IP based on your current network IP

So, we will do checking every second. Simple string comparison is not time-consuming so it's acceptable:

This will set the NTP server IP depending on your current IP. Don't worry about multiple calls to CFG_SetNTPServer. The flash config will be saved only if there is a change in the settings.
The similiar behaviour was requested by user here:
https://www.elektroda.com/rtvforum/topic4054813.html


6. How to debug drivers (on Windows)?
OpenBeken can run on Windows, along with device simulator.
So if you run our MSVC projects, you can put breakpoints in drivers:

This way you can:
- see variable values
- see current call stack
- pause or resume execution, also manually step in/out the calls
This can substantially reduce your testing and development time.

7. How to make drivers scriptable?
The best way is to use console commands. Console commands can be invoked via autoexec.bat, HTTP interface or even by MQTT. Creating a new command is very simple:

This way you cam get a console/script command with a full arguments testing.



Of course, channel value can be also used as an argument.



8. How to access channels and measurements?
Any driver can have full access to OBK API, so you can easily read and write channels, read measurements, etc:

The following code will log the channel 1 value and voltage (from BL0942/BL0937/etc sensor).

This way you can also, for example, measure how long voltage is above given value:

If you want, you can change the hardcoded 230 value to something set via console command, just look at the console command sample and save the value to the static global variable.
Then you can set channels and even publish data via MQTT:


9. How to make custom Web page interface?
Per-driver main HTTP page callback can be used also to get user input. You can easily create HTML forms that way. For this example, I will create a simple button that will just toggle the channel 5:

Clicking the button toggles channel 5 value:



And that's it! That's how you can create a custom driver in OBK. Remember to download our code to check the full API that is available for your development. All details related to arguments of MQTT/channel/etc calls are in our repository.