RUI3 System API

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_READ	Read permission allows for reading a variable data only and disables any write functionality.
RAK_ATCMD_PERM_WRITE	Write permission allows for writing a variable data only and disables any read functionality.
RAK_ATCMD_PERM_WRITEONCEREAD	Special functionality that allows for setting variable once and only allows for reading after.
RAK_ATCMD_PERM_DISABLE	Disables the AT command from being used.

RAK_TIMER_ID

The RAK timer ID's

enum RAK_TIMER_ID

Enumerator
RAK_TIMER_0	Timer # 0.
RAK_TIMER_1	Timer # 1.
RAK_TIMER_2	Timer # 2.
RAK_TIMER_3	Timer # 3.
RAK_TIMER_4	Timer # 4.

RAK_TIMER_MODE

The RAK timer modes

enum RAK_TIMER_MODE

Enumerator
RAK_TIMER_ONESHOT	One shot timer, does trigger only once.
RAK_TIMER_PERIODIC	Repeating timer

RUI_WAKEUP_TRIGGER_MODE

The RAK timer modes

enum RUI_WAKEUP_TRIGGER_MODE

Enumerator
RUI_WAKEUP_RISING_EDGE	RUI wakeup on rising edge of GPIO
RUI_WAKEUP_FALLING_EDGE	RUI 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()

Function	const string get()
Returns	firmware 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)

Function	const string get()
Parameterss	version firmware version for user to be set(Type: String)
Returns	bool • 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()

Function	const string get()
Returns	cli 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()

Function	bool set()
Parameters	version cli version for user to be set(Type: String)
Returns	bool • 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()

Function	const string get()
Returns	API 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()

Function	const string get()
Returns	model 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)

Function	const string get()
Parameters	model ID for user to be set(Type: String)
Returns	bool • 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()

Function	const string get()
Returns	chip 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()

Function	float get(void)
Returns	float (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)

Function	bool get(uint32_t offset, uint8_t * buf, uint32_t len)
Parameters	offset - 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)
Returns	bool • 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)

Function	bool set(uint32_t offset, uint8_t * buf, uint32_t len)
Parameters	offset - 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)
Returns	bool • 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 Mode	Comments
RAK_TIMER_ONESHOT	Timer triggered one time
RAK_TIMER_PERIODIC	Timer 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 ID	Comments
RAK_TIMER_0	timer ID #0
RAK_TIMER_1	timer ID #1
RAK_TIMER_2	timer ID #2
RAK_TIMER_3	timer ID #3
RAK_TIMER_4	timer ID #4

create()

api.system.timer.create()

Function	bool api.system.timer.create(id, handler, mode)
Parameters	id - is the Timer ID handler - the handler function for this Timer mode - the mode of this Timer (RAK_TIMER_ONESHOT or RAK_TIMER_PERIODIC )
Returns	bool • 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()

Function	bool api.system.timer.start(id, ms, data)
Parameters	id - is the Timer ID ms - is the period of Timer (milliseconds) data - the data passed to Timer handler function
Returns	bool • 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()

Function	bool api.system.timer.stop(id)
Parameters	id - is the Timer ID
Returns	bool • 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()

Function	uint8_t get(void)
Parameters	id - is the Timer ID
Returns	1 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)

Function	bool set(uint8_t value)
Parameters	value 1 for low power mode enabled 0 for low power mode disabled
Returns	bool • 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();

Function	void cpu(int ms_time = POWERSAVE_NO_TIMEOUT)
Parameters	ms_time(optional) - Duration for cpu to sleep(default = no timeout)
Returns	void

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();

Function	void lora(int ms_time = POWERSAVE_NO_TIMEOUT)
Parameters	ms_time(optional) - Duration for cpu to sleep(default = no timeout)
Returns	void

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();

Function	void all(int ms_time = POWERSAVE_NO_TIMEOUT)
Parameters	ms_time(optional) - Duration for all component to sleep(default = no timeout)
Returns	void

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);

Function	api.system.sleep.registerWakeupCallback(POWER_SAVE_HANDLER callback);
Parameters	callback - Pointer to the function to be called
Returns	bool • 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 Mode	Description
RUI_WAKEUP_RISING_EDGE	Trigger wake up on rising edge.
RUI_WAKEUP_FALLING_EDGE	Trigger wake up on falling edge.

Function	void setup(RUI_WAKEUP_TRIGGER_MODE mode, uint32_t pin)
Parameters	mode - This decide to use Rising or Falling trigger mode. pin - This is the pin to be chosen as the wake up source.
Returns	void

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);

Function	uint8_t get(void)
Returns	uint8_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);

Function	uint8_t get(void)
Parameters	value - Low Power Mode 0 == off, 1 == on
Returns	bool • TRUE 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);

Function	bool set(char * passwd_Char, size_t len) bool set(char * passwd_Str, size_t len)
Parameters	passwd_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
Returns	bool - 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();

Function	void lock(void)
Returns	void

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();

Function	void unlock(void)
Returns	void

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)

Function	bool set(char* buf , uint32_t len)
Parameters	buf - the buffer to set alias name len - the length of alias name( < = 16 bytes)
Returns	• TRUE 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)

Function	bool get(char* buf , uint32_t len)
Parameters	buf - the buffer to get alias name len - the length of alias name( < = 16 bytes)
Returns	• TRUE 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()

Function	void reboot()
Returns	void

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()

Function	void restoreDefault()
Returns	void

Click to view the code

void setup()
{
  api.system.restoreDefault();
}

void loop()
{
}