RUI3

https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/
Admin
RUI3 (RAK Unified Interface V3) is an IoT development framework for RAK LPWAN modules that supports...
Tokens:203,085
Snippets:848
Trust Score:10
Update:11 months ago
Show doc for...
Tokens:
Raw
### Example: Stop BLE Advertising on Setup

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble

An example Arduino sketch demonstrating how to stop BLE advertising during the setup phase.

```cpp
void setup()  
{
  api.ble.advertise.stop();  
}
  
void loop()  
{
}
```

--------------------------------

### Start BLE Advertising with Timeout (RUI3 API)

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble-configuration

Starts BLE advertising and sets a timeout period. The example sets the timeout to 60 seconds. This function is crucial for making the device discoverable by other BLE devices.

```c++
if (!(ret = api.ble.advertise.start(60))) {
      Serial.printf("BLE Configuration - set start advertise parameter is incorrect! \r\n");
    return;
}
```

--------------------------------

### Example: P2P Encryption Setup and Communication

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/lorawan

This example demonstrates setting up P2P mode encryption and communication using the RAK API. It initializes the serial communication, configures various P2P parameters including encryption, and then enters a loop for sending and receiving data.

```C++
long startTime;
uint8_t node_encrypt_key[16] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08};
uint8_t encrypt_buff[16];

void setup()
{
    Serial.begin(115200);
    startTime = millis();

    Serial.println("P2P Start");

    Serial.printf("Set Node device work mode %s\r\n", api.lora.nwm.set() ? "Success" : "Fail");
    Serial.printf("Set P2P mode frequency %s\r\n", api.lora.pfreq.set(868000000) ? "Success" : "Fail");
    Serial.printf("Set P2P mode spreading factor %s\r\n", api.lora.psf.set(12) ? "Success" : "Fail");
    Serial.printf("Set P2P mode bandwidth %s\r\n", api.lora.pbw.set(125) ? "Success" : "Fail");
    Serial.printf("Set P2P mode code rate %s\r\n", api.lora.pcr.set(0) ? "Success" : "Fail");
    Serial.printf("Set P2P mode preamble length %s\r\n", api.lora.ppl.set(8) ? "Success" : "Fail");
    Serial.printf("Set P2P mode tx power %s\r\n", api.lora.ptp.set(22) ? "Success" : "Fail");
    Serial.printf("Set P2P mode encryption status %s\r\n", api.lora.encry.set(1) ? "Success" : "Fail");
    Serial.printf("Set P2P mode encryption Key %s\r\n\r\n", api.lora.enckey.set(node_encrypt_key, 16) ? "Success" : "Fail");

    Serial.printf("P2P encryption status = %s\r\n", api.lora.encry.get() ? "Enable" : "Disable");

    api.lora.enckey.get(encrypt_buff, 16);
    Serial.printf("P2P encryption Key = 0x");
        for (int i = 0 ; i < 16 ; i++) {
            Serial.printf("%02X", encrypt_buff[i]);
        }
    Serial.println("");

    randomSeed(millis());
}

void loop()
{
    uint8_t payload[] = "payload";

    int rxDelay = random(3000, 5000);

    // Receive P2P data every 10 seconds
    if(millis() - startTime >= 10*1000) {
      Serial.printf("P2P Rx start for %d millisSeconds\r\n", rxDelay);
      startTime = millis();
      Serial.printf("P2P set Rx mode %s\r\n",api.lora.precv(rxDelay) ? "Success" : "Fail");
      delay(rxDelay);
    } else {

      Serial.printf("P2P send %s\r\n", api.lora.psend(sizeof(payload), payload)? "Success" : "Fail");
      delay(1000);
    }
}
```

--------------------------------

### Complete LoRaWAN Application Example in C++

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/lorawan

A comprehensive example demonstrating the setup and operation of a LoRaWAN device using the RUI3 API. It includes device configuration, joining the network, registering callbacks for various events (receive, join, send), and sending data periodically. This code requires prior initialization of serial communication and setting of LoRaWAN parameters like AppEUI, AppKey, and Device EUI.

```C++
void recv_cb(SERVICE_LORA_RECEIVE_T *data) {
  Serial.println("Something received!");
  for (int i = 0 ; i < data->BufferSize ; i++) {
    Serial.printf("%x", data->Buffer[i]);
  }
  Serial.print("\r\n");
}

void join_cb(int32_t status) {
  Serial.printf("Join status: %d\r\n", status);
}

void send_cb(int32_t status) {
  Serial.printf("Send status: %d\r\n", status);
}

// OTAA Device EUI MSB
uint8_t node_device_eui[8] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08};
// OTAA Application EUI MSB
uint8_t node_app_eui[8] = {0x0E, 0x0D, 0x0D, 0x01, 0x0E, 0x01, 0x02, 0x03};
// OTAA Application Key MSB
uint8_t node_app_key[16] = {0x2B, 0x7E, 0x15, 0x16, 0x28, 0xAE, 0xD2, 0xA6, 0xAB, 0xF7, 0x15, 0x88, 0x09, 0xCF, 0x4F, 0x3C};

void setup()
{
    Serial.begin(115200);

    api.lorawan.appeui.set(node_app_eui, 8);
    api.lorawan.appkey.set(node_app_key, 16);
    api.lorawan.deui.set(node_device_eui, 8);

    api.lorawan.band.set(4);
    api.lorawan.njm.set(1); // Network Join Method: 1 for OTAA
    api.lorawan.join();
    api.lorawan.registerRecvCallback(recv_cb);
    api.lorawan.registerJoinCallback(join_cb);
    api.lorawan.registerSendCallback(send_cb);

    //wait for Join success
    while (api.lorawan.njs.get() == 0)
    {
      Serial.print("Waiting for Lorawan join...");
      api.lorawan.join();
      delay(10000);
    }
}

void loop()
{
    uint8_t payload[] = "example";

    if (api.lorawan.send(sizeof(payload), payload, 129, true, 1)) {
        Serial.println("Send Success");
    } else {
        Serial.println("Send fail");

    }

    delay(5000);
}
```

--------------------------------

### Compile RAK3172 Example with Visual Studio IDE

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/supported-ide

Steps to compile and upload an example project for the RAK3172 using Visual Studio IDE and the Visual Micro extension. The process includes selecting the correct board, opening an example from the Visual Micro Explorer, configuring the project, and flashing the firmware to the device.

--------------------------------

### Compile RAK4631-R Example with Visual Studio IDE

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/supported-ide

Instructions to compile and upload an example project for the RAK4631-R using Visual Studio IDE with the Visual Micro extension. This involves opening an example from the Visual Micro Explorer, configuring project settings, and then building and uploading the firmware.

```text
ATE  

AT+VER=?  
```

--------------------------------

### RAKwireless BLE Customer API Initialization and Start

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble

Initializes the RAKwireless BLE customer API and starts the BLE service.

```APIDOC
## POST /websites/rakwireless_product-categories_software-apis-and-libraries_rui3/api_ble_customer_start

### Description
Initializes the RAKwireless BLE customer API and starts the BLE service.

### Method
POST

### Endpoint
`/websites/rakwireless_product-categories_software-apis-and-libraries_rui3/api_ble_customer_start`

### Parameters
*No parameters required.*

### Request Example
```json
{ 
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the BLE customer API was initialized and started successfully.

#### Response Example
```json
{
  "status": "ble_customer_api_started"
}
```
```

--------------------------------

### RAKOneWireSerial Class Initialization and Usage Example

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/one-wire-serial

Demonstrates the initialization of the RAKOneWireSerial class and its usage within setup and loop functions. It shows how to set up the serial communication, write data, and read received data. Note the warning about callback functionality in RUI3 V4.1.0.

```cpp
RAKOneWireSerial onewire(UART1_RXD_PIN,NULL);

       void setup()
       {
           Serial.begin(115200);
           onewire.begin(115200, RAK_CUSTOM_MODE);
       }

       void loop()
       {
            onewire.write("data\r\n");
            while(onewire.available())
            {
                char a = onewire.read();
                Serial.printf("%c",a);
            }
       }

```

--------------------------------

### RUI3 BLE UART Stop Example

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble

A simple C code snippet demonstrating how to stop the BLE UART service within the setup() function. This example shows a basic implementation for initializing and configuring BLE UART.

```c
void setup()
{
  api.ble.uart.stop();
}

void loop()
{
}
```

--------------------------------

### Arduino BLE Example with Notify and Callbacks

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble

A comprehensive Arduino C++ example demonstrating BLE setup using RAKwireless libraries. It includes initializing services and characteristics, setting properties and permissions, and implementing callbacks for CCCD write events (notifications) and data read/write events. The example shows how to enable notifications for heart rate measurements and set the body sensor location.

```cpp
#include "Arduino.h"
#define UUID16_SVC_HEART_RATE 0x180D
#define UUID16_CHR_HEART_RATE_MEASUREMENT 0x2A37
#define UUID16_CHR_BODY_SENSOR_LOCATION 0x2A38

RAKBleCharacteristic hrmc = RAKBleCharacteristic(UUID16_CHR_HEART_RATE_MEASUREMENT);

void cccd_callback(uint16_t chars_uuid, uint8_t *cccd_value)
{
    if (chars_uuid == UUID16_CHR_HEART_RATE_MEASUREMENT)
    {
        if (hrmc.notifyEnabled())
        {
            Serial.println("[Heart Rate Measurement 'Notify' enabled]");
        }
        else
        {
            Serial.println("[Heart Rate Measurement 'Notify' disabled]");
            return;
        }
    }
    Serial.println("");
    Serial.print("chars_uuid: ");
    Serial.print("0x");
    String uuid_str = String(chars_uuid, HEX);
    Serial.println(uuid_str);
    Serial.println("notify value:");
    String cccd_value1 = String(cccd_value[0], HEX);
    String cccd_value2 = String(cccd_value[1], HEX);
    Serial.print("0x");
    Serial.println(cccd_value1);
    Serial.print("0x");
    Serial.println(cccd_value2);
}

void send_callback(uint16_t chars_uuid, uint8_t *send_value)
{
    if (chars_uuid == UUID16_CHR_BODY_SENSOR_LOCATION)
    {
        Serial.println("[Heart Rate - Body Sensor Location Read!]");
        Serial.print("chars_uuid: ");
        Serial.print("0x");
        String uuid_str = String(chars_uuid, HEX);
        Serial.println(uuid_str);
        Serial.println("");
        Serial.print("send value: ");
        char send_str = send_value[0];
        Serial.println(send_str);
    }
}

void setup()
{
    uint8_t base_uuid[]={0xB3, 0x20, 0xF8, 0xFA, 0x5A, 0xFC, 0x4C, 0x1B, 0xB9, 0x6F, 0x16, 0x24, 0x7D, 0x91, 0x2D, 0x0A};
    Serial.begin(115200);
    delay(5000);
    Serial.println("RAKwireless BLE Customer Services Example");
    Serial.println("------------------------------------------------------");
    api.ble.customer.init();
    RAKBleService hrms = RAKBleService(base_uuid);
    RAKBleCharacteristic bslc = RAKBleCharacteristic(UUID16_CHR_BODY_SENSOR_LOCATION);
    hrms.begin();

    hrmc.setProperties(RAK_CHR_PROPS_NOTIFY);
    hrmc.setPermission(RAK_SET_OPEN);
    hrmc.setFixedLen(2);
    hrmc.setCccdWriteCallback(cccd_callback);
    hrmc.begin();
    delay(1000);
    uint8_t hrmdata[2] = {0x39, 0x40};
    hrmc.notify(hrmdata);
    delay(1000);

    bslc.setProperties(RAK_CHR_PROPS_READ);
    bslc.setPermission(RAK_SET_OPEN);
    bslc.setFixedLen(1);
    bslc.setWriteCallback(send_callback);
    bslc.begin();
    delay(1000);
    uint8_t sensor_location[1] = {'2'};  // Set the characteristic to 'Wrist' (2)
    bslc.write(sensor_location);

    api.ble.customer.start();
}

void loop()
{
}

```

--------------------------------

### OneWireSerial begin Method Example

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/one-wire-serial

Example of using the begin method to set the baud rate and mode for OneWire serial communication. This function initializes the serial communication parameters.

```cpp
RAKOneWireSerial onewire(UART1_RXD_PIN,NULL);
       void setup()
       {
           Serial.begin(115200);
           onewire.begin(115200, RAK_CUSTOM_MODE);
       }

       void loop()
       {
            onewire.write("data\r\n");
            while(onewire.available())
            {
                char a = onewire.read();
                Serial.printf("%c",a);
            }
       }

```

--------------------------------

### Full P2P Encryption Setup and Status Check - RUI3 Example

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/lorawan

This C++ code demonstrates how to configure P2P mode settings, including enabling encryption and setting an encryption key, and then retrieving the encryption status using the `api.lora.encry.get()` function. It utilizes the RAKwireless RUI3 LoRa library and includes serial output for status updates and debugging.

```C++
long startTime;
uint8_t node_encrypt_key[16] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08};
uint8_t encrypt_buff[16];

void setup()
{
    Serial.begin(115200);
    startTime = millis();

    Serial.println("P2P Start");

    Serial.printf("Set Node device work mode %s\r\n", api.lora.nwm.set() ? "Success" : "Fail");
    Serial.printf("Set P2P mode frequency %s\r\n", api.lora.pfreq.set(868000000) ? "Success" : "Fail");
    Serial.printf("Set P2P mode spreading factor %s\r\n", api.lora.psf.set(12) ? "Success" : "Fail");
    Serial.printf("Set P2P mode bandwidth %s\r\n", api.lora.pbw.set(125) ? "Success" : "Fail");
    Serial.printf("Set P2P mode code rate %s\r\n", api.lora.pcr.set(0) ? "Success" : "Fail");
    Serial.printf("Set P2P mode preamble length %s\r\n", api.lora.ppl.set(8) ? "Success" : "Fail");
    Serial.printf("Set P2P mode tx power %s\r\n", api.lora.ptp.set(22) ? "Success" : "Fail");
    Serial.printf("Set P2P mode encryption status %s\r\n", api.lora.encry.set(1) ? "Success" : "Fail");
    Serial.printf("Set P2P mode encryption Key %s\r\n\r\n", api.lora.enckey.set(node_encrypt_key, 16) ? "Success" : "Fail");
    Serial.printf("P2P encryption status = %s\r\n", api.lora.encry.get() ? "Enable" : "Disable");

    api.lora.enckey.get(encrypt_buff, 16);
    Serial.printf("P2P encryption Key = 0x");
        for (int i = 0 ; i < 16 ; i++) {
            Serial.printf("%02X", encrypt_buff[i]);
        }
    Serial.println("");

    randomSeed(millis());
}

void loop()
{
    uint8_t payload[] = "payload";

    int rxDelay = random(3000, 5000);

    // Receive P2P data every 10 seconds
    if(millis() - startTime >= 10*1000) {
      Serial.printf("P2P Rx start for %d millisSeconds\r\n", rxDelay);
      startTime = millis();
      Serial.printf("P2P set Rx mode %s\r\n",api.lora.precv(rxDelay) ? "Success" : "Fail");
      delay(rxDelay);
    } else {

      Serial.printf("P2P send %s\r\n", api.lora.psend(sizeof(payload), payload)? "Success" : "Fail");
      delay(1000);
    }

}
```

--------------------------------

### RAKCONFIGURATION API Example

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble

Example demonstrating the usage of RAKBleCharacteristic and RAKBleService for setting up Heart Rate Measurement and Body Sensor Location characteristics.

```APIDOC
## RAKCONFIGURATION API Example

### Description
This example demonstrates the setup and configuration of BLE services and characteristics using the RAKwireless RUI3 API, specifically focusing on Heart Rate Measurement and Body Sensor Location.

### Method
Multiple methods used, including `init()`, `begin()`, `setProperties()`, `setPermission()`, `setFixedLen()`, `setCccdWriteCallback()`, `notify()`, `setWriteCallback()`, and `write()`.

### Endpoint
N/A (This is an SDK/library usage example)

### Parameters
See individual API documentation for parameters.

### Request Example
```cpp
#include "Arduino.h"
#define UUID16_SVC_HEART_RATE 0x180D
#define UUID16_CHR_HEART_RATE_MEASUREMENT 0x2A37
#define UUID16_CHR_BODY_SENSOR_LOCATION 0x2A38

RAKBleCharacteristic hrmc = RAKBleCharacteristic(UUID16_CHR_HEART_RATE_MEASUREMENT);

void cccd_callback(uint16_t chars_uuid, uint8_t *cccd_value) {
    if (chars_uuid == UUID16_CHR_HEART_RATE_MEASUREMENT) {
        if (hrmc.notifyEnabled()) {
            Serial.println("[Heart Rate Measurement 'Notify' enabled]");
        } else {
            Serial.println("[Heart Rate Measurement 'Notify' disabled]");
            return;
        }
    }
    Serial.println("");
    Serial.print("chars_uuid: ");
    Serial.print("0x");
    String uuid_str = String(chars_uuid, HEX);
    Serial.println(uuid_str);
    Serial.println("notify value:");
    String cccd_value1 = String(cccd_value[0], HEX);
    String cccd_value2 = String(cccd_value[1], HEX);
    Serial.print("0x");
    Serial.println(cccd_value1);
    Serial.print("0x");
    Serial.println(cccd_value2);
}

void send_callback(uint16_t chars_uuid, uint8_t *send_value) {
    if (chars_uuid == UUID16_CHR_BODY_SENSOR_LOCATION) {
        Serial.println("[Heart Rate - Body Sensor Location Read!]");
        Serial.print("chars_uuid: ");
        Serial.print("0x");
        String uuid_str = String(chars_uuid, HEX);
        Serial.println(uuid_str);
        Serial.println("");
        Serial.print("send value: ");
        char send_str = send_value[0];
        Serial.println(send_str);
    }
}

void setup() {
    uint8_t base_uuid[]={0xB3, 0x20, 0xF8, 0xFA, 0x5A, 0xFC, 0x4C, 0x1B, 0xB9, 0x6F, 0x16, 0x24, 0x7D, 0x91, 0x2D, 0x0A};
    Serial.begin(115200);
    delay(5000);
    Serial.println("RAKwireless BLE Customer Services Example");
    Serial.println("------------------------------------------------------");
    api.ble.customer.init();
    RAKBleService hrms = RAKBleService(base_uuid);
    RAKBleCharacteristic bslc = RAKBleCharacteristic(UUID16_CHR_BODY_SENSOR_LOCATION);
    hrms.begin();
    hrmc.setProperties(RAK_CHR_PROPS_NOTIFY);
    hrmc.setPermission(RAK_SET_OPEN);
    hrmc.setFixedLen(2);
    hrmc.setCccdWriteCallback(cccd_callback);
    hrmc.begin();
    delay(1000);
    uint8_t hrmdata[2] = {0x39, 0x40};
    hrmc.notify(hrmdata);
    delay(1000);
    bslc.setProperties(RAK_CHR_PROPS_READ);
    bslc.setPermission(RAK_SET_OPEN);
    bslc.setFixedLen(1);
    bslc.setWriteCallback(send_callback);
    bslc.begin();
    delay(1000);
    uint8_t sensor_location[1] = {'2'}; // '2' for Wrist
    bslc.write(sensor_location);
    api.ble.customer.start();
}

void loop() {
}
```

### Response
#### Success Response (200)
N/A (This is an SDK/library usage example)

#### Response Example
N/A
```

--------------------------------

### ATZ Command Example - MCU Reset

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/at-command-manual

This example shows the ATZ command, used to trigger a reset on the RUI3 module. The output includes the device information displayed after the reset.

```plaintext
ATZ
RAKwireless RAK3172
------------------------------------------------------
Version: RUI_4.0.4_RAK3172-E
Current Work Mode: LoRa P2P.

```

--------------------------------

### Start RF Tone Test

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/at-command-manual

This command starts an RF tone test, utilized for RF certification. If the frequency tone process is already running, an AT_BUSY_ERROR is returned.

```plaintext
AT+TTONE
Tx toneOK
```

--------------------------------

### BLE Scanner Start API

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble

Starts scanning for BLE peripherals and parsing their advertising data.

```APIDOC
## POST /api/ble/scanner/start

### Description
This API starts scanning for BLE peripherals in range and parsing the advertising data that is being sent out by the peripherals.

### Method
POST

### Endpoint
/api/ble/scanner/start

### Parameters
#### Request Body
- **timeout_sec** (uint16_t) - Required - The number of seconds after which scanning will stop. If `timeout_sec=0`, scanning will continue indefinitely.

### Request Example
```json
{
  "timeout_sec": 60
}
```

### Response
#### Success Response (200)
This endpoint does not return a specific success response body, indicating the operation has been initiated.

#### Response Example
(No specific response body for success, operation is asynchronous)
```

--------------------------------

### Install FUSE on Linux for Arduino IDE

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/supported-ide

This snippet provides the commands to install FUSE on a Linux system, a prerequisite for running Arduino IDE AppImages. Ensure FUSE is installed before attempting to run the Arduino IDE.

```bash
sudo add-apt-repository universe
sudo apt install libfuse2
```

--------------------------------

### Get RUI Bootloader Version AT+BOOTVER

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/at-command-manual

This AT command retrieves the version of the RUI bootloader. It can be queried to get the version string or set with a new value. The input and output are typically string-based.

```text
AT+BOOTVER=?
AT+BOOTVER=************
OK
```

--------------------------------

### setup() - Sleep Setup

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/system

Configures the sleep function by setting the wake-up trigger mode (rising or falling edge) and the specific GPIO pin to be used as the wake-up source.

```APIDOC
## POST /api/system/sleep/setup

### Description
Sets up the sleep functionality by configuring the wake-up trigger mode and the GPIO pin.

### Method
POST

### Endpoint
`/api/system/sleep/setup`

### Parameters
#### Request Body
- **mode** (string) - Required - The wake-up trigger mode. Accepted values are `RUI_WAKEUP_RISING_EDGE` or `RUI_WAKEUP_FALLING_EDGE`.
- **pin** (uint32_t) - Required - The GPIO pin number to be used as the wake-up source.

### Request Example
```json
{
  "mode": "RUI_WAKEUP_FALLING_EDGE",
  "pin": 32
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success or failure of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### ATE Command Example - AT Command Echo

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/at-command-manual

This example demonstrates the ATE command, which toggles the AT command echo on the serial terminal. It shows how to enable the echo and the expected 'OK' response.

```plaintext
ATE
OK

```

--------------------------------

### Start BLE Advertising

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble

Starts BLE advertising after configuring settings. Accepts an advertising timeout in seconds; a value of 0 means advertising never stops. Returns a boolean indicating success or failure.

```c++
api.ble.advertise.start(adv_time)
```

--------------------------------

### RUI3 AT Command Format Examples

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/at-command-manual

Illustrates the standard format for RUI3 AT commands, including how to query command information, execute commands, retrieve command values, and set command values. It also shows the expected response structure.

```AT Command
AT+XXX? 
AT+XXX 
AT+XXX=? 
AT+XXX=<value>
```

```AT Command
AT+XXX=<value>

<CR><LF><Status><CR><LF>


```

--------------------------------

### AT+SN Command Example - Get Serial Number

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/at-command-manual

This example demonstrates how to retrieve the device's serial number using the AT+SN? command. It shows the expected output format for the serial number.

```plaintext
AT+SN=?
9181004E20900057
OK

```

--------------------------------

### RAKBleService Instance Creation and Begin

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble

Demonstrates how to create a `RAKBleService` instance using a base UUID and then calling `begin()` to activate it.

```APIDOC
## POST /websites/rakwireless_product-categories_software-apis-and-libraries_rui3/service_begin

### Description
Creates a `RAKBleService` instance and calls `begin()` to activate it.

### Method
POST

### Endpoint
`/websites/rakwireless_product-categories_software-apis-and-libraries_rui3/service_begin`

### Parameters
#### Request Body
- **base_uuid** (array of bytes) - Required - The base UUID for the BLE service.

### Request Example
```json
{
  "base_uuid": [0xB3, 0x20, 0xF8, 0xFA, 0x5A, 0xFC, 0x4C, 0x1B, 0xB9, 0x6F, 0x16, 0x24, 0x7D, 0x91, 0x2D, 0x0A]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the service was created and begun successfully.

#### Response Example
```json
{
  "status": "service_activated"
}
```
```

--------------------------------

### Get Battery Level using RUI3 API

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/system

Gets the current battery level of the device as a float value in Volts. The example initializes serial communication and prints the battery level every second.

```C/C++
void setup()
{
    Serial.begin(115200);
}

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

--------------------------------

### Get Device MAC Address (RUI3 API)

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble-configuration

Fetches the MAC address of the BLE device at a specified position. The example requests the MAC address at position 2. This is useful for identifying specific devices or network configurations.

```c++
char *get_position_2_mac_addr = api.ble.mac.get(2);
```

--------------------------------

### RAKBleCharacteristic::begin()

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble

After adding a characteristic, you must call `begin()` to complete the configuration and make it active.

```APIDOC
## POST /websites/rakwireless_product-categories_software-apis-and-libraries_rui3/begin

### Description
Completes the configuration of a BLE characteristic after it has been added.

### Method
POST

### Endpoint
`/websites/rakwireless_product-categories_software-apis-and-libraries_rui3/begin`

### Parameters
#### Request Body
- **bslc** (RAKBleCharacteristic) - Required - The RAKBleCharacteristic instance to begin.

### Request Example
```json
{
  "bslc": "instance_of_RAKBleCharacteristic"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the operation was successful.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Get LoRaWAN Join RX Window 1 Delay using C++

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/lorawan

This API retrieves the join delay for the first reception window (RX1). The function returns an integer representing the delay in milliseconds. The example demonstrates setting and then getting this value.

```cpp
void setup() {
    Serial.begin(115200);
  
    Serial.printf("Set the join delay on RX window 1  %s\r\n", api.lorawan.jn1dl.set(5000) ? "Success" : "Fail");
}

void loop() {
    Serial.printf("The join delay on RX window 1 is %d\r\n", api.lorawan.jn1dl.get());
    delay(1000);
}
```

--------------------------------

### AT+P2P - P2P Parameters Configuration

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/at-command-manual

This command provides comprehensive configuration of all parameters for the P2P mode. You can view all parameters, query the format, or set specific parameters.

```APIDOC
## AT+P2P

### Description
Provides configuration of all parameters for the P2P mode.

### Method
AT Command

### Endpoint
N/A

### Parameters
#### Query Parameters
- **?** (string) - Optional - Used to view all P2P parameters.
- **=?** (string) - Optional - Used to query the format for setting P2P parameters.
- **=<param>** (string) - Optional - Sets P2P parameters. Format: `<Frequency>:<Spreading Factor>:<Bandwidth>:<Code Rate>:<Preamble Length>:<TX Power>`

### Request Example
```
AT+P2P=?
AT+P2P=868000000:7:0:0:20:14
OK

AT+P2P=868:12:300:3:200:14
AT_PARAM_ERROR
```

### Response
#### Success Response (OK)
- **AT+P2P** (string) - Returns the current P2P parameters or confirms the setting.

#### Response Example
```
AT+P2P: get or set all P2P parameters
OK

AT+P2P=868000000:7:0:0:20:14
OK
```

#### Error Handling
- `AT_PARAM_ERROR`: Returned when setting a wrong or malformed value.
- `AT_BUSY_ERROR`: Returned when the device is busy.

#### Parameter Details
- **Frequency**: Range: 150000000-960000000.
- **Spreading Factor (SF)**: Range: 6, 7, 8, 9, 10, 11, 12.
- **Bandwidth**: 0=125KHz, 1=250KHz, 2=500KHz, 3=7.8KHz, 4=10.4KHz, 5=15.63KHz, 6=20.83KHz, 7=31.25KHz, 8=41.67KHz, 9=62.5KHz.
- **Code Rate (CR)**: 0=4/5, 1=4/6, 2=4/7, 3=4/8.
- **Preamble Length**: Range: 2-65535.
- **TX Power**: Range: 5-22.

**Note**: Default value is “868000000:7:125:0:8:14”.
```

--------------------------------

### Set and Get Network Working Mode (Arduino)

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/lorawan

Demonstrates how to set and get the network working mode using the RAKwireless RUI3 Arduino API. It shows initialization of serial communication and then uses `api.lorawan.nwm.set()` and `api.lorawan.nwm.get()` within setup and loop functions.

```arduino
void setup()
{
    Serial.begin(115200);

    Serial.printf("Set the network working mode %s\r\n", api.lorawan.nwm.set() ? "Success" : "Fail");
}

void loop()
{
    Serial.printf("Network working mode = %s\r\n", api.lorawan.nwm.get() ? "LoRaWan" : "P2P");

    delay(1000);
}
```

--------------------------------

### Start RF RSSI Tone Test

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/at-command-manual

Initiates an RF RSSI tone test. The command can be queried to get the RSSI value (-115 dBm) or to start the test. If the radio frequency RSSI process is already active, an AT_BUSY_ERROR is returned. This command is primarily for RF certification testing.

```plaintext
AT+TRSSI=?
Rx FSK Test
RSSI Value -115 dBm
OK
```

--------------------------------

### Set and Get LoRa Region using C++

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/lorawan

This C++ code demonstrates how to set and then get the LoRaWAN region. The `setup()` function sets the region to EU868 (value 4) and prints the success status. The `loop()` function continuously retrieves and prints the current LoRa region. Ensure `api.lorawan.band.set()` is called with a valid region value.

```cpp
void setup()
{
    Serial.begin(115200);
  
    Serial.printf("Set LoRa region %s\r\n", api.lorawan.band.set(4) ? "Success" : "Fail");
}

void loop()
{
    Serial.printf("LoRa region = %d\r\n", api.lorawan.band.get());

    delay(1000);
}
```

--------------------------------

### Configure P2P IQ Inversion with AT+IQINVER

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/at-command-manual

This command enables or disables P2P IQ Inversion. Input '1' for ON and '0' for OFF. Setting an invalid value will trigger an AT_PARAM_ERROR.

```bash
AT+IQINVER?
AT+IQINVER: get or set P2P IQ inversion (1 = ON, 0 = OFF)
OK

AT+IQINVER=?
AT+IQINVER=0
OK
```

--------------------------------

### Bootloader Commands

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/at-command-manual

This section covers AT commands related to the bootloader, including checking versions, status, and controlling boot mode.

```APIDOC
## AT+VER

### Description
Retrieves the version of the bootloader.

### Method
AT Command

### Endpoint
N/A (AT Command)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
AT+VER=?
```

### Response
#### Success Response (200)
- **version** (string) - The bootloader version string (e.g., `RUI_BOOT_0.6_STM32WLE5CC`).

#### Response Example
```
RUI_BOOT_0.6_STM32WLE5CC
```
```

```APIDOC
## AT+VERSION

### Description
Retrieves the version of the bootloader.

### Method
AT Command

### Endpoint
N/A (AT Command)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
AT+VERSION
```

### Response
#### Success Response (200)
- **version** (string) - The bootloader version string (e.g., `RUI_BOOT_0.6_STM32WLE5CC`).

#### Response Example
```
RUI_BOOT_0.6_STM32WLE5CC
```
```

```APIDOC
## AT+BOOTSTATUS

### Description
Gets the current status of the bootloader.

### Method
AT Command

### Endpoint
N/A (AT Command)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
AT+BOOTSTATUS
```

### Response
#### Success Response (200)
- **status** (string) - The current bootloader status (e.g., `Boot Mode`).

#### Response Example
```
Boot Mode
```
```

```APIDOC
## AT+RUN

### Description
Leaves boot mode and boots into the application.

### Method
AT Command

### Endpoint
N/A (AT Command)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
AT+RUN
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message (e.g., `Stop Boot Mode`).

#### Response Example
```
Stop Boot Mode
```
```

```APIDOC
## AT+RESET

### Description
Resets the device.

### Method
AT Command

### Endpoint
N/A (AT Command)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```
AT+RESET
```

### Response
#### Success Response (200)
(No specific return value documented for success, typically implies reset initiated.)

#### Response Example
```
(Device resets)
```
```

--------------------------------

### Get LoRaWAN Network Session Key (nwkskey) - C++ Example

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/lorawan

This C++ code example demonstrates how to retrieve the LoRaWAN network session key (nwkskey) using the RUI3 API. It requires a buffer and its length (16 bytes) as parameters. The function returns a boolean indicating the success or failure of the operation. This function is only applicable in ABP mode.

```cpp
// ABP Network Session Key  
uint8_t node_nwk_skey[16] = {0xD6, 0x03, 0x37, 0xAC, 0x97, 0x4C, 0x43, 0x2F, 0xF3, 0x7A, 0xF9, 0xA7, 0x9B, 0xE8, 0x50, 0xF7};

void setup()
{
    Serial.begin(115200);

    api.lorawan.njm.set(RAK_LORA_ABP); // Set LoRaWan join mode to ABP  

    if(api.lorawan.nwkskey.set(node_nwk_skey, 16) == true)
        Serial.println("LoRaWan network session key set success");
    else
        Serial.println("LoRaWan network session key set fail");
}

void loop()
{
    uint8_t buff[16];

    if(api.lorawan.nwkskey.get(buff, 16) == true) {
        Serial.print("LoRaWan network session key = 0x");
        for(int i = 0; i < 16; i++) {
            Serial.printf("%02X", buff[i]);
        }
        Serial.println("");
    } else {
        Serial.println("LoRaWan network session key get fail");
    }

    delay(1000);
}
```

--------------------------------

### Example AT Command Usage in RUI3

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/serial-operating-modes

This snippet demonstrates the interaction with RUI3 in AT command mode, showing how to query device information using an AT command and the expected response.

```text
AT+APPEUI=?
0102030405060708
OK
```

--------------------------------

### Get and Set Duty Cycle

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/lorawan

These APIs control the duty cycle setting for LoRaWAN communication. The get() method returns a boolean indicating whether the duty cycle is enabled or disabled. The set(value) method takes a boolean parameter to enable (true) or disable (false) the duty cycle. The example code demonstrates enabling the duty cycle and then checking its status.

```c++
void setup()
{
    Serial.begin(115200);

    Serial.printf("Enable duty cycle  %s\r\n", api.lorawan.dcs.set(1) ? "Success" : "Fail");
}

void loop()
{
    Serial.printf("Duty cycle is  %s\r\n", api.lorawan.adr.get() ? "Enable" : "Disable");
    delay(1000);
}
```

--------------------------------

### Get Hardware ID AT+HWID

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/at-command-manual

This AT command retrieves the hardware ID string of the device. When queried, it returns a string representing the module's hardware ID, for example, 'nrf52840'. No input parameters are necessary.

```text
AT+HWID=?
AT+HWID=nrf52840
OK
```

--------------------------------

### AT+PBR - P2P FSK Bitrate

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/at-command-manual

Configure the P2P FSK modem bitrate. Supports querying the current setting, available bitrates, and setting a specific bitrate.

```APIDOC
## AT+PBR - P2P FSK Bitrate

### Description
Gets or sets the P2P FSK modem bitrate. Supports querying the current setting, available bitrates, and setting a specific bitrate.

### Method
AT Command

### Endpoint
N/A (Serial Interface)

### Parameters
#### Input Parameters
- **`AT+PBR?`**: Queries the current P2P FSK modem bitrate.
- **`AT+PBR=?`**: Queries the range of available FSK bitrates.
- **`<fbitrate>`** (integer) - Required: The desired bitrate in bits per second (b/s). Range: 600 to 300000.

#### Query Parameters
None

#### Request Body
None

### Request Example
```
AT+PBR=?
AT+PBR=4915
OK

AT+PBR=4915
OK
```

### Response
#### Success Response (OK)
- **`AT+PBR: <fbitrate>`**: Returned when querying the current bitrate.
- **`<fbitrate>`**: Returned when querying available bitrates.

#### Response Example
```
AT+PBR=4915
OK
```

### Error Handling
- **`AT_PARAM_ERROR`**: Returned when setting a wrong or malformed value.
```

--------------------------------

### Get BLE Advertising Interval (RUI3 API)

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble-configuration

Retrieves the current advertising interval in milliseconds. This value determines how frequently the device advertises its presence. The function returns an integer representing the interval.

```c++
int32_t get_adv_interval = api.ble.settings.advertiseInterval.get();
```

--------------------------------

### Restore Default Settings - C/C++

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/system

Restores the device to its default factory settings using the `api.system.restoreDefault()` function. This action is typically performed once during the `setup` phase of the program.

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

void loop()
{
}
```

--------------------------------

### Get Chip ID using RUI3 API

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/system

Retrieves the unique chip ID of the device. The function returns the chip ID as a string. This example shows how to initialize serial communication and print the chip ID.

```C/C++
void setup()
{
    Serial.begin(115200);
}

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

--------------------------------

### Start RAKBleCustomer Service in C++

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble

Activates the configured BLE custom services after all services and characteristics have been set up. This function should be called once all BLE configurations are complete to make the custom services operational.

```cpp
api.ble.customer.start()
```

--------------------------------

### Get BLE Advertise Status (RUI3 API)

Source: https://docs.rakwireless.com/product-categories/software-apis-and-libraries/rui3/ble-configuration

Retrieves the current advertising status of the BLE device. This function is useful for monitoring the state of BLE advertising. It returns the status, but specific return values are not detailed.

```c++
get_dav_status = api.ble.advertise.status();
```
Tokens:
Raw