Skip to main content

System

RUI System Data Type

Typedefs

typedef void(* RAK_TIMER_HANDLER) (void *data)

typedef void(* RAK_TASK_HANDLER) (void)

Enumerations

RAK_AT_PERMISSION

The permission setting of AT command

enum RAK_AT_PERMISSION
Enumerator
RAK_ATCMD_PERM_READRead permission allows for reading a variable data only and disables any write functionality.
RAK_ATCMD_PERM_WRITEWrite permission allows for writing a variable data only and disables any read functionality.
RAK_ATCMD_PERM_WRITEONCEREADSpecial functionality that allows for setting variable once and only allows for reading after.
RAK_ATCMD_PERM_DISABLEDisables the AT command from being used.

RAK_TIMER_ID

The RAK timer ID's

enum RAK_TIMER_ID
Enumerator
RAK_TIMER_0Timer # 0.
RAK_TIMER_1Timer # 1.
RAK_TIMER_2Timer # 2.
RAK_TIMER_3Timer # 3.
RAK_TIMER_4Timer # 4.

RAK_TIMER_MODE

The RAK timer modes

enum RAK_TIMER_MODE
Enumerator
RAK_TIMER_ONESHOTOne shot timer, does trigger only once.
RAK_TIMER_PERIODICRepeating timer

RUI_WAKEUP_TRIGGER_MODE

The RAK timer modes

enum RUI_WAKEUP_TRIGGER_MODE
Enumerator
RUI_WAKEUP_RISING_EDGERUI wakeup on rising edge of GPIO
RUI_WAKEUP_FALLING_EDGERUI wakeup on falling edge of GPIO

Device Information

Firmware Version

get()

This API allows the user to get the firmware version.

api.system.firmwareVersion.get()
Functionconst string get()
Returnsfirmware version(Type: string)
Click to view the code
void setup()
{
Serial.begin(115200);
}

void loop()
{
Serial.printf("Firmware Version: %s\r\n", api.system.firmwareVersion.get().c_str());
delay(1000);
}

set()

This API allows the user to set the firmware version.

warning

Changing the firmware version will make the firmware incompatible with WisToolBox.

api.system.firmwareVersion.set(String version)
Functionconst string get()
Parameterssversion firmware version for user to be set(Type: String)
Returnsbool
TRUE for successfully setting firmware version
FALSE for setting firmware version fail
Click to view the code
void setup()
{
Serial.begin(115200);
}

void loop()
{
Serial.printf("Firmware Version: %s\r\n", api.system.firmwareVersion.get().c_str());
delay(1000);
}

CLI Version

get()

This API allows the user to get the cli version.

api.system.cliVersion.get()
Functionconst string get()
Returnscli version(Type: string)
Click to view the code
void setup()
{
Serial.begin(115200);
}

void loop()
{
Serial.printf("AT Command Version: %s\r\n", api.system.cliVersion.get().c_str());
delay(1000);
}

set()

This API allows the user to set the cli version.

warning

Changing the CLI version will make the firmware incompatible with WisToolBox.

api.system.cliVersion.set()
Functionbool set()
Parametersversion cli version for user to be set(Type: String)
Returnsbool
TRUE for successfully setting cli version
FALSE for setting cli version fail
Click to view the code
void setup()
{
Serial.begin(115200);
}

void loop()
{
String version = "your version"
api.system.cliVer.set(version);
delay(1000);
}

API Version

get()

This API allows the user to get the API version.

api.system.apiVersion.get()
Functionconst string get()
ReturnsAPI version(Type: string)
Click to view the code
void setup()
{
Serial.begin(115200);
}

void loop()
{
Serial.printf("RUI API Version: %s\r\n", api.system.apiVersion.get().c_str());
delay(1000);
}

Model ID

get()

This API allows the user to get the model ID.

api.system.modelId.get()
Functionconst string get()
Returnsmodel ID(Type: string)
Click to view the code
void setup()
{
Serial.begin(115200);
}

void loop()
{
Serial.printf("Model ID: %s\r\n", api.system.modelId.get().c_str());
delay(1000);
}

set()

This API allows the user to set the model ID

warning

Changing the model ID will make the firmware incompatible with WisToolBox!

api.system.hwModel.set(model_id)
Functionconst string get()
Parametersmodel ID for user to be set(Type: String)
Returnsbool
TRUE for successfully set model ID
FALSE for set model ID fail
Click to view the code
void setup()
{
Serial.begin(115200);
}

void loop()
{
Serial.printf("Model ID: %s\r\n", api.system.modelId.get().c_str());
delay(1000);
}

Chip ID

get()

This API allows the user to get the chip ID.

api.system.chipId.get()
Functionconst string get()
Returnschip ID(Type: string)
Click to view the code
void setup()
{
Serial.begin(115200);
}

void loop()
{
Serial.printf("Hardware ID: %s\r\n", api.system.chipId.get().c_str());
delay(1000);
}

Battery

get()

Gets the current battery level.

api.system.bat.get()
Functionfloat get(void)
Returnsfloat (Unit: V)
Click to view the code
void setup()
{
Serial.begin(115200);
}

void loop()
{
Serial.printf("Battery Level: %f\r\n", api.system.bat.get());
delay(1000);
}

Flash

get()

Reads a range of data from user flash partition.

api.system.flash.get(offset, buf, len)
Functionbool get(uint32_t offset, uint8_t * buf, uint32_t len)
Parametersoffset - the offset to the start of user flash partition (The sum of offset and length can't exceed 0x7800. If the chip is nRF52840 (e.g. RAK4631), this limitation becomes 0x20000)
buf - the buffer for reading the data
len - the length of data (The sum of offset and length can't exceed 0x7800. If the chip is nRF52840 (e.g. RAK4631), this limitation becomes 0x20000)
Returnsbool
TRUE for reading data successfully
FALSE for reading data failure
Click to view the code
void setup()
{
Serial.begin(115200);
delay(2000);
uint8_t flash_value[4] = {0};
bool wr_result = false;
uint32_t data_to_save = 12345678;
flash_value[0] = (uint8_t)(data_to_save >> 0);
flash_value[1] = (uint8_t)(data_to_save >> 8);
flash_value[2] = (uint8_t)(data_to_save >> 16);
flash_value[3] = (uint8_t)(data_to_save >> 24);

wr_result = api.system.flash.set(0, flash_value, 4);
}

void loop()
{
uint8_t flash_read[4] = {0};
uint32_t flash_data = 0;

if (api.system.flash.get(0, flash_read, 4))
{
flash_data |= flash_read[0] << 0;
flash_data |= flash_read[1] << 8;
flash_data |= flash_read[2] << 16;
flash_data |= flash_read[3] << 24;
Serial.println(flash_data);
}
else
{
Serial.println("Failed to read data from Flash");
}

delay(2000);
}

set()

Writes a range of data to user flash partition.

api.system.flash.set(offset, buf, len)
Functionbool set(uint32_t offset, uint8_t * buf, uint32_t len)
Parametersoffset - the offset to the start of user flash partition (The sum of offset and length can't exceed 0x7800. If the chip is nRF52840(e.g. RAK4631), this limitation becomes 0x20000)
buf - the buffer for writing the data
len - the length of data (The sum of offset and length can't exceed 0x7800. If the chip is nRF52840(e.g. RAK4631), this limitation becomes 0x20000)
Returnsbool
TRUE for writing data successfully
FALSE for writing data failure
Click to view the code
void setup()
{
Serial.begin(115200);
delay(2000);
uint8_t flash_value[4] = {0};
bool wr_result = false;
uint32_t data_to_save = 12345678;
flash_value[0] = (uint8_t)(data_to_save >> 0);
flash_value[1] = (uint8_t)(data_to_save >> 8);
flash_value[2] = (uint8_t)(data_to_save >> 16);
flash_value[3] = (uint8_t)(data_to_save >> 24);

wr_result = api.system.flash.set(0, flash_value, 4);
}

void loop()
{
uint8_t flash_read[4] = {0};
uint32_t flash_data = 0;

if (api.system.flash.get(0, flash_read, 4))
{
flash_data |= flash_read[0] << 0;
flash_data |= flash_read[1] << 8;
flash_data |= flash_read[2] << 16;
flash_data |= flash_read[3] << 24;
Serial.println(flash_data);
}
else
{
Serial.println("Failed to read data from Flash");
}

delay(2000);
}

Timer

On RUI3 Timer API, there are two different Timer modes based on the trigger.

Timer ModeComments
RAK_TIMER_ONESHOTTimer triggered one time
RAK_TIMER_PERIODICTimer triggered periodically

The timer control is performed via Timer ID. The Timer ID definition is shown below. 5 timers are available for the user application

Timer IDComments
RAK_TIMER_0timer ID #0
RAK_TIMER_1timer ID #1
RAK_TIMER_2timer ID #2
RAK_TIMER_3timer ID #3
RAK_TIMER_4timer ID #4

create()

api.system.timer.create()
Functionbool api.system.timer.create(id, handler, mode)
Parametersid - is the Timer ID
handler - the handler function for this Timer
mode - the mode of this Timer (RAK_TIMER_ONESHOT or RAK_TIMER_PERIODIC )
Returnsbool
TRUE for creating Timer successfully
FALSE for creating Timer failure
Click to view the code
void handler(void *data)
{
Serial.printf("[%lu]This is the Timer handler function\r\n", millis());
}

void setup()
{
Serial.begin(115200);
if (api.system.timer.create(RAK_TIMER_0, (RAK_TIMER_HANDLER)handler, RAK_TIMER_PERIODIC) != true) {
Serial.printf("Creating timer failed.\r\n");
} else if (api.system.timer.start(RAK_TIMER_0, 1000, NULL) != true) {
Serial.printf("Starting timer failed.\r\n");
}
}

start()

api.system.timer.start()
Functionbool api.system.timer.start(id, ms, data)
Parametersid - is the Timer ID
ms - is the period of Timer (milliseconds)
data - the data passed to Timer handler function
Returnsbool
TRUE for starting Timer successfully
FALSE for starting Timer failure
Click to view the code
void handler(void *data)
{
Serial.printf("[%lu]This is the Timer handler function\r\n", millis());
}

void setup()
{
Serial.begin(115200);
if (api.system.timer.create(RAK_TIMER_0, (RAK_TIMER_HANDLER)handler, RAK_TIMER_PERIODIC) != true) {
Serial.printf("Creating timer failed.\r\n");
} else if (api.system.timer.start(RAK_TIMER_0, 1000, NULL) != true) {
Serial.printf("Starting timer failed.\r\n");
}
}

stop()

api.system.timer.stop()
Functionbool api.system.timer.stop(id)
Parametersid - is the Timer ID
Returnsbool
TRUE for stoping Timer successfully
FALSE for stoping Timer failure
Click to view the code
void handler(void *data)
{
Serial.printf("[%lu]This is the Timer handler function\r\n", millis());
}

void setup()
{
Serial.begin(115200);
if (api.system.timer.create(RAK_TIMER_0, (RAK_TIMER_HANDLER)handler, RAK_TIMER_PERIODIC) != true) {
Serial.printf("Creating timer failed.\r\n");
} else if (api.system.timer.start(RAK_TIMER_0, 1000, NULL) != true) {
Serial.printf("Starting timer failed.\r\n");
}
}

void loop()
{
if (millis() > 60000) {
if (api.system.timer.stop(RAK_TIMER_0) != true) {
Serial.printf("Stoping timer failed.\r\n");
}
}
}

Powersave

lpm()

This API sets and gets the low power mode

get()

Get current LPM settings

api.system.lpm.get()
Functionuint8_t get(void)
Parametersid - is the Timer ID
Returns1 for low power mode enabled
0 for low power mode disabled
Click to view the code
void setup()
{
Serial.begin(115200);

Serial.printf("Set the low power mode %s\n\r", api.system.lpm.set(1) ? "Success" : "Fail");
}

void loop()
{
Serial.printf("The low power mode = %d\n\r", api.system.lpm.get());

delay(1000);
}

set()

Set current LPM settings

api.system.lpm.set(uint8_t  	value)
Functionbool set(uint8_t value)
Parametersvalue
1 for low power mode enabled
0 for low power mode disabled
Returnsbool
• TRUE for setting low power mode success
• FALSE for setting low power mode failure
Click to view the code
void setup()
{
Serial.begin(115200);

Serial.printf("Set the low power mode %s\n\r", api.system.lpm.set(1) ? "Success" : "Fail");
}

void loop()
{
Serial.printf("The low power mode = %d\n\r", api.system.lpm.get());

delay(1000);
}

cpu()

Sleeps the cpu with default no timeout.

api.system.sleep.cpu();
Functionvoid cpu(int ms_time = POWERSAVE_NO_TIMEOUT)
Parametersms_time(optional) - Duration for cpu to sleep(default = no timeout)
Returnsvoid
Click to view the code
void setup()
{
}

void loop()
{
api.system.sleep.cpu(1000);
}

lora()

Sleeps lora with default no timeout.

api.system.sleep.lora();
Functionvoid lora(int ms_time = POWERSAVE_NO_TIMEOUT)
Parametersms_time(optional) - Duration for cpu to sleep(default = no timeout)
Returnsvoid
Click to view the code
void setup()
{
}

void loop()
{
api.system.sleep.lora(1000);
}

all()

Sleeps all the component with default no timeout.

api.system.sleep.all();
Functionvoid all(int ms_time = POWERSAVE_NO_TIMEOUT)
Parametersms_time(optional) - Duration for all component to sleep(default = no timeout)
Returnsvoid
Click to view the code
void setup()
{
}

void loop()
{
api.system.sleep.all(1000);
}

registerWakeupCallback()

This registers a wakeup callback function. The wakeup is triggered by an GPIO pin that is setup with api.system.sleep.setup.

api.system.sleep.registerWakeupCallback(POWER_SAVE_HANDLER callback);
Functionapi.system.sleep.registerWakeupCallback(POWER_SAVE_HANDLER callback);
Parameterscallback - Pointer to the function to be called
Returnsbool
TRUE = add callback function success
FALSE = add callback function fail
Click to view the code
void WakeupCallback()
{
Serial.printf("This is Wakeup Callback\r\n");
}

void setup()
{
Serial.begin(115200);
api.system.sleep.setup(RUI_WAKEUP_FALLING_EDGE, 12);
if ( api.system.sleep.registerWakeupCallback(WakeupCallback) == false )
{
Serial.println("Create Wakeup Callback failed.");
}
}

void loop()
{
api.system.sleep.cpu(1000);
}

setup()

Sets up the sleep function.

api.system.sleep.setup(mode, pin);

On sleep mode, the device wake up trigger can be configured.

Trigger ModeDescription
RUI_WAKEUP_RISING_EDGETrigger wake up on rising edge.
RUI_WAKEUP_FALLING_EDGETrigger wake up on falling edge.
Functionvoid setup(RUI_WAKEUP_TRIGGER_MODE mode, uint32_t pin)
Parametersmode - This decide to use Rising or Falling trigger mode.
pin - This is the pin to be chosen as the wake up source.
Returnsvoid
Click to view the code
void setup()
{
api.system.sleep.setup(RUI_WAKEUP_FALLING_EDGE, 32);
}

void loop()
{
api.system.sleep.all(1000);
}

lpm

This API sets and gets the low power mode of the device.

get()

Gets up the low power mode status.

uint8_t api.system.lpm.get(void);
Functionuint8_t get(void)
Returnsuint8_t - Low Power Mode 0 == off, 1 == on
Click to view the code
void setup()
{
Serial.begin(115200);

Serial.printf("Set the low power mode %s\n\r", api.system.lpm.set(1) ? "Success" : "Fail");
}

void loop()
{
Serial.printf("The low power mode = %d\n\r", api.system.lpm.get());

delay(1000);
}

set()

Set up the low power mode.

bool api.system.lpm.set(uint8_t value);
Functionuint8_t get(void)
Parametersvalue - Low Power Mode 0 == off, 1 == on
ReturnsboolTRUE if low power mode could be enabled or disabled, FALSE if failure (not supported)
Click to view the code
void setup()
{
Serial.begin(115200);

Serial.printf("Set the low power mode %s\n\r", api.system.lpm.set(1) ? "Success" : "Fail");
}

void loop()
{
Serial.printf("The low power mode = %d\n\r", api.system.lpm.get());

delay(1000);
}

Misc

pword

Allows the application to lock the default Serial port and protect it with a password

set

This API allows the user to set a 1~8 digits password to lock the default serial.

api.system.pword.set(passwd_Str);
api.system.pword.set(passwd_Char, len);
Functionbool set(char * passwd_Char, size_t len) bool set(char * passwd_Str, size_t len)
Parameterspasswd_Str - a string to set for unlocking the device
passwd_Char - a char array to set for unlocking the device
len - the length of your password
Returnsbool
- TRUE - for successfully set a password
- FALSE - for set a password failure
Click to view the code

Example:

int loopCount = 0;

void setup()
{
String password = "12345678";
api.system.pword.set(password); // set the password to 12345678
api.system.pword.lock(); // lock the default port
}

void loop()
{
loopCount++;

if (loopCount == 60)
api.system.pword.unlock(); // unlock the default port after 60 seconds

delay(1000);
}

lock

This API allows the user to lock the default serial with the pass set in api.system.pword.set().

api.system.pword.lock();
Functionvoid lock(void)
Returnsvoid
Click to view the code

Example:

int loopCount = 0;

void setup()
{
String password = "12345678";
api.system.pword.set(password); // set the password to 12345678
api.system.pword.lock(); // lock the default port
}

void loop()
{
loopCount++;

if (loopCount == 60)
api.system.pword.unlock(); // unlock the default port after 60 seconds

delay(1000);
}

unlock

This API allows the user to unlock the default serial without password when it is locked.

api.system.pword.unlock();
Functionvoid unlock(void)
Returnsvoid
Click to view the code

Example:

int loopCount = 0;

void setup()
{
String password = "12345678";
api.system.pword.set(password); // set the password to 12345678
api.system.pword.lock(); // lock the default port
}

void loop()
{
loopCount++;

if (loopCount == 60)
api.system.pword.unlock(); // unlock the default port after 60 seconds

delay(1000);
}

alias

set()

Sets the alias name for device.

api.system.alias.set(buf, len)
Functionbool set(char* buf , uint32_t len)
Parametersbuf - the buffer to set alias name
len - the length of alias name( < = 16 bytes)
ReturnsTRUE for setting alias name successfully
FALSE for setting alias name failure
NOTE

Then length len on setting the alias must be the same on the size of the alias name.

Click to view the code
void setup()
{
Serial.begin(115200);
api.system.alias.set("my device",9);
char buf[16];
Serial.println(api.system.alias.get(buf,16));
Serial.println(buf);
}
void loop()
{
}

get()

Gets the alias name for device.

api.system.alias.get(buf, len)
Functionbool get(char* buf , uint32_t len)
Parametersbuf - the buffer to get alias name
len - the length of alias name( < = 16 bytes)
ReturnsTRUE for getting alias name successfully
FALSE for getting alias name failure
Click to view the code
void setup()
{
Serial.begin(115200);
api.system.alias.set("my device",9);
char buf[16];
Serial.println(api.system.alias.get(buf,16));
Serial.println(buf);
}
void loop()
{
}

atMode

add()

Provides developers to create AT CMD.

api.system.atMode.add(cmd, usage, title, handle, perm)

| Function | bool add(char *cmd, char *usage, char *title, PF_handle handle,unsigned int perm = RAK_ATCMD_PERM_WRITE | RAK_ATCMD_PERM_READ); | |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Parameters | • cmd - the cmd to define cmd name
usage - the cmd usage
title - the cmd title
handle - the handler that this command will execute
perm - the cmd execution permission |

Click to view the code
uint32_t led_status;

int led_handle(SERIAL_PORT port, char *cmd, stParam *param) {
if (param->argc == 1 && !strcmp(param->argv[0], "?")) {
Serial.print(cmd);
Serial.print("=");
Serial.println(led_status?"HIGH":"LOW");
} else if (param->argc == 1) {
for (int i = 0 ; i < strlen(param->argv[0]) ; i++) {
if (!isdigit(*(param->argv[0]+i))) {
return AT_PARAM_ERROR;
}
}

led_status = strtoul(param->argv[0], NULL, 10);
if (led_status != 0 && led_status != 1) {
return AT_PARAM_ERROR;
}

pinMode(GREEN_LED, OUTPUT);
pinMode(BLUE_LED, OUTPUT);
digitalWrite(GREEN_LED, (led_status == 1)?HIGH:LOW);
digitalWrite(BLUE_LED, (led_status == 1)?HIGH:LOW);
} else {
return AT_PARAM_ERROR;
}

return AT_OK;
}

void setup()
{
api.system.atMode.add("LED", "This controls both green and blue LEDs.", "LED", led_handle, RAK_ATCMD_PERM_WRITE | RAK_ATCMD_PERM_READ);
}

void loop()
{
}

CHANGE_ATCMD_PERM

Changes AT command permission.

PERMISSION LEVEL:

  • RAK_ATCMD_PERM_READ
  • RAK_ATCMD_PERM_WRITE
  • RAK_ATCMD_PERM_WRITEONCEREAD,
  • RAK_ATCMD_PERM_DISABLE

AT commands' default permission are RAK_ATCMD_PERM_READ | RAK_ATCMD_PERM_WRITE.

#define CHANGE_ATCMD_PERM(_atcmd_name, _atcmd_perm)

Value:

    ATCMD_ITEM(atcmd_queue, atcmd_permission_item UNIQUE_NAME(permissions)) =   \
{ \
.atcmd_id = _atcmd_name, \
.permission = _atcmd_perm, \
}
Click to view the code
CHANGE_ATCMD_PERM("AT+APPKEY", RAK_ATCMD_PERM_READ);
CHANGE_ATCMD_PERM("AT+APPSKEY", RAK_ATCMD_PERM_WRITE);
CHANGE_ATCMD_PERM("AT+DEVADDR", RAK_ATCMD_PERM_WRITEONCEREAD);
CHANGE_ATCMD_PERM("AT+APPEUI", RAK_ATCMD_PERM_DISABLE);
CHANGE_ATCMD_PERM("AT+NETID", RAK_ATCMD_PERM_READ | RAK_ATCMD_PERM_WRITE);
CHANGE_ATCMD_PERM("AT+ALIAS", RAK_ATCMD_PERM_READ | RAK_ATCMD_PERM_WRITE);
CHANGE_ATCMD_PERM("AT+HWID", RAK_ATCMD_PERM_READ | RAK_ATCMD_PERM_WRITE);

void setup()
{
}

void loop()
{
}

reboot()

api.system.reboot()
Functionvoid reboot()
Returnsvoid
Click to view the code
int loopCount = 0;

void setup()
{
}

void loop()
{
loopCount++;

if(loopCount == 60)
api.system.reboot(); // Reboot after 60 seconds

delay(1000);
}

restoreDefault()

api.system.restoreDefault()
Functionvoid restoreDefault()
Returnsvoid
Click to view the code
void setup()
{
api.system.restoreDefault();
}

void loop()
{
}