Skip to main content
X

RAK3372 WisBlock LPWAN Module Quick Start Guide

This quick start guide shows how can you use the RAK3372 as a WisBlock Core module. It is a step-by-step guide on how to prepare your hardware as well as how to set up the needed software.

There are more features and applications possible for RAK3372 WisBlock Core but this guide only demonstrates LED Breathing and LoRaWAN OTAA example.

Following this guide successfully ensures that you have a working RAK3372 WisBlock Core.

This guide also includes instructions on how to perform firmware update.

Prerequisite​

Package Inclusions​

Before going through each step in the installation guide of the RAK3372 WisBlock Core Module, make sure to prepare the necessary items listed below:

Hardware​

Software​

Arduino IDE​
warning

If you are using Windows 10:
Do NOT install the Arduino IDE from the Microsoft App Store. Instead, install the original Arduino IDE from the Arduino official website. The Arduino app from the Microsoft App Store has problems using third-party Board Support Packages.

https://raw.githubusercontent.com/RAKWireless/RAKwireless-Arduino-BSP-Index/main/package_rakwireless.com_rui_index.json

After that, you can then add RAKwireless RUI STM32 Boards via Arduino board manager.

Product Configuration​

Hardware Setup​

Your RAK3372 will not work on its own. It needs at least to be connected to a WisBlock Base together with an antenna. You can then interface various WisBlock Modules via the available slots in the WisBlock Base. You can also add a battery as a power source and optional solar charging. All hardware-related configurations for your RAK3372 are discussed here.

This section covers:

RAK3372 to WisBlock Base​

The RAK3372 will not work without a WisBlock Base board. The WisBlock Base provides a USB connection for programming the RAK3372. It also provides a power source and various interfaces to RAK3372 so that it can be connected to other WisBlock Modules via different module slots.

RAKwireless offers many WisBlock Base Boards compatible with WisBlock Core. It is highly recommended to look at these WisBlock Base boards to see what matches your requirements in terms of available module slots, power supply options, and overall size.

warning

To illustrate, RAK3372 can be connected to RAK19007 WisBlock Base, as shown in Figure 1.

Figure 4790: RAK3372 connection to WisBlock Base RAK19007

Some pins are exposed on RAK19007, and you can easily use them via header pins. The labels are at the back, as shown in Figure 2.

Figure 4791: WisBlock Base exposed pins

Each WisBlock Base board has its own set of header pins available for you to use. However, these header pins are not exactly the same in each WisBlock Base. It is common to see IO pins and communication protocol pins like I2C and UART in the WisBlock Base board. More information can be found on the official documentation of the specific WisBlock Base you used in your project.

You can access the AT command via UART2 by default (and also possible via UART1). Firmware update is only possible via UART2. A built-in USB-Serial converter is on the board to easily connect the RAK3372 to the USB port of the PC.

There are useable LEDs as well in the WisBlock Base. You can control them in your code via the GREEN_LED and BLUE_RED macro.

Assembling and Disassembling of WisBlock Modules​

Assembling​

Figure 3 shows how to mount the RAK3372 module on top of a WisBlock Base board (RAK19007). Follow carefully the procedure defined in WisBlock module assembly/disassembly instructions to secure the connection safely. Once attached, carefully fix the module with one or more pieces of M1.2 x 3 mm screws depending on the module.

Figure 4792: RAK3372 mounting sketch
Disassembling​

The procedure in disassembling any type of WisBlock module is the same.

  1. First, remove the screws.
Figure 4793: Removing screws from the WisBlock module
  1. Once the screws are removed, check the silkscreen of the module to find the correct location where force can be applied.
Figure 4794: Detaching silkscreen on the WisBlock module
  1. Apply force to the module at the position of the connector, as shown in Figure 6, to detach the module from the baseboard.
Figure 4795: Applying even forces on the proper location of a WisBlock module

LoRa Antenna​

Another important component of RAK3372 is the antenna.

Figure 4796: LoRa antenna

You need to ensure that it is properly connected to have a good LoRa signal. Also, note that you can damage the RF section of the chip if you power the module without an antenna connected to the IPEX connector.

Figure 4797: RAK3372 IPEX antenna connector
NOTE

Detailed information about the RAK3372 LoRa PCB antenna can be found on the antenna datasheet. Keep in mind that the PCB antenna is intended ideally only for prototyping and device evaluation. For enterprise deployments, it is advisable to consider a better antenna for reliable performance.

warning
  • When using the LoRa transceiver, make sure that it is connected to an antenna. Using the transceiver chip without an antenna can damage the system.
  • Make sure to fix the module with screws to ensure proper function.

Battery and Solar Connection​

RAK3372 can be powered via the USB cable or Li-Ion/LiPo battery via the dedicated connectors, as shown in Figure 9. The matching connector for the battery wires is a JST PHR-2 2 mm pitch female.

This illustration uses RAK19007 as WisBlock Base. There are other WisBlock Base boards available, and you need to check the datasheet of the specific WisBlock Base board for the right polarity and other parameters.

warning
  • Batteries can cause harm if not handled properly.
  • Only 3.7-4.2 V Rechargeable LiPo batteries are supported. It is highly recommended not to use other types of batteries with the system unless you know what you are doing.
  • If a non-rechargeable battery is used, it has to be unplugged first before connecting the USB cable to the USB port of the board to configure the device. Not doing so might damage the battery or cause a fire.
  • Only 5 V solar panels are supported. Do not use 12 V solar panels. It will destroy the charging unit and eventually other electronic parts.
  • Make sure the battery wires match the polarity on the baseboard. Not all batteries have the same wiring.
Figure 4798: WisBlock Base Battery Connection

The battery can be recharged, as well, via a small solar panel, as shown in Figure 10. The matching connector for the solar panel wires is an JST ZHR-2 1.5 mm pitch female.

Figure 4799: Solar panel connection

Specifications of the battery and solar panel can be found on the datasheet of the WisBlock Base.

Software Initial Guide​

Software Setup​

The default firmware of RAK3372 is based on RUI3, which allows you to develop your custom firmware to connect sensors and other peripherals to it. To develop your custom firmware using Arduino IDE, you need first to add RAKwireless RUI STM32 Boards in the Arduino board manager, which will be discussed in this guide. You can then use RUI3 APIs for your intended application. You can upload the custom firmware via UART. The AT commands of RAK3372 is still available even if you compile custom firmware via RUI3. You can send AT commands via UART2 connection.

RAK3372 RUI3 Board Support Package in Arduino IDE​

If you don't have an Arduino IDE yet, you can download it from the Arduino official website and follow the installation procedure depending on your machine.

NOTE

For Windows 10 and up users: If your Arduino IDE is installed from the Microsoft App Store, you need to reinstall your Arduino IDE by getting it from the Arduino official website. The Arduino app from the Microsoft App Store has problems using third-party Board Support Packages.

Once the Arduino IDE has been installed successfully, you can now configure the IDE to add the RAK3372 to its board selection by following these steps.

  1. Open Arduino IDE and go to File > Preferences.
Figure 4800: Arduino preferences
  1. To add the RAK3372 to your Arduino Boards list, edit the Additional Board Manager URLs. Click the icon, as shown in Figure 12.
Figure 4801: Modifying Additional Board Manager URLs
  1. Copy the URL below and paste it on the field, as shown in Figure 13. If there are other URLs already there, just add them on the next line. After adding the URL, click OK.
https://raw.githubusercontent.com/RAKWireless/RAKwireless-Arduino-BSP-Index/main/package_rakwireless.com_rui_index.json
Figure 4802: Add additional board manager URLs

  1. Restart the Arduino IDE.

  2. Open the Boards Manager from Tools Menu.

Figure 4803: Opening Arduino boards manager

  1. Write RAK in the search bar, as shown in Figure 15. This will show the available RAKwireless module boards that you can add to your Arduino Board list.

  2. Click on the area highlighted in blue to select RAKwireless RUI STM32 Boards. Install the latest version of the RAKwireless RUI STM32 Boards by clicking the Install button.

Figure 4804: Installing RAKwireless RUI STM32 Boards
Configure RAK3372 on Boards Manager​
  1. Once the BSP is installed, select Tools > Boards Manager > RAKWireless RUI STM32 Modules > WisDuo RAK3172 Evaluation Board. The RAK3372 WisBlock Core uses the RAK3172 WisDuo module, so you must select that board as shown in Figure 16.
Figure 4805: Selecting RAK3172 Module
RAK3372 COM Port on Device Manager​

Connect the RAK3372 via UART and check RAK3372 COM Port using Windows Device Manager.

Figure 4806: Device manager ports (COM & LPT)
Compile an Example with Arduino LED Breathing​

  1. After completing the steps on adding your RAK3372 WisBlock Core to the Arduino IDE, you can now try to run a simple program to test your setup. There is a built-in LED in the WisBlock Base board that you can control via RUI3 custom firmware.

  2. Launch Arduino IDE and configure WisDuo RAK3172 Evaluation Board on board selection. See Figure 16.

  3. Connect the RAK3372 via UART and check RAK3372 COM Port. See Figure 17.

  4. Open the Tools Menu and select a COM port. COM28 is currently used. COM port number varies depending on the PC.

Figure 4807: Select COM port
  1. You can now see the serial monitor icon and click it to connect the COM port.
Figure 4808: Open Arduino serial monitor
  1. If the connection is successful, you can send AT Commands to RAK3372. For example: To check the RUI version, type AT+VER=? on the text area, then click on the Send button, as shown in Figure 20. If there is no reply, make sure you have selected the right COM port or double-check the USB connection.
Figure 4809: Send AT command and Arduino serial monitor COM28
  1. Open Arduino_Led_Breathing example code.
Figure 4810: Arduino Led Breathing example
  1. Click on the Verify icon to check if you have successfully compiled the example code.
Figure 4811: Verify the example code
  1. Click the Upload icon to send the compiled firmware to your RAK3372 WisBlock Core module.
NOTE

RAK3172 module in the WisBlock Core should automatically go to BOOT mode when the firmware is uploaded via Arduino IDE.

Figure 4812: Upload the example code
  1. If the upload is successful, you will see the Upgrade Complete message.
Figure 4813: Device programmed successfully
  1. After the Device Programmed is completed, you will see that LEDs are blinking.
LoRaWAN Example​

This example illustrates how to program RAK3372 WisBlock Core as a stand-alone LoRaWAN end-device via RUI3 Arduino APIs. To use the RAK3372 WisBlock Core module as a LoRaWAN end-device, it needs to be within reach of a working LoRaWAN gateway registered to a LoRaWAN network server (LNS) or with a built-in network server.

NOTE

If you are new to LoRaWAN, here are a few good references about LoRaWAN and gateways:

RAKwireless LoRaWAN gateway models like WisGate Edge have built-in network servers. It is also common that the LoRaWAN network server is external or in the cloud. The popular LoRaWAN network server in the cloud that you can use for free (but offers enterprise service, too) is TTN.

To correctly run this example, it is necessary to configure the LoRaWAN parameters and create an OTAA application on your LoRaWAN gateway.

Register the LoRaWAN Gateway on TTNv3 Community Edition​

After configuring your gateway, you need to register it in TTNv3:

  1. Log in to the TTNv3 Network Server with a web browser.
  1. Navigate to the Console page and click on gateway icon, as shown in Figure 25.
Figure 4814: TTNv3 gateway registration and configuration
  1. On General Settings, enter the Gateway ID, Gateway EUI, and Gateway Name. This information is available in your LoRaWAN gateway configuration. Select the Gateway Server address according to the region where the LoRaWAN gateway will be installed.
Figure 4815: TTNv3 gateway registration and configuration
  1. Select the Frequency plan for your region (used by TTN), then click on the Create gateway button. This will add a new gateway to TTNv3.
Figure 4816: TTNv3 add new Gateway
Creating LoRaWAN Applications in TTN​
  1. The first step is to go to The Things Network platform and select a cluster, as shown in Figure 28.
Figure 4817: Selecting Cluster in TTN V3

You can use the same login credentials on the TTN V2 if you have one. If you have no account yet, you need to create one.

  1. To register as a new user to TTN, click on Login with The Things ID then select register on the next page, as shown in Figure 29 and Figure 30.
Figure 4818: Login using TTN account
Figure 4819: Registration of new account

  1. You should now be on the step of creating your TTN account. Fill in all the necessary details and activate your account.

  2. After creating an account, you should log in on the platform using your username/email and password then click Submit, as shown in Figure 31.

Figure 4820: Logging in to TTN platform
  1. Click Authorize to proceed.
Figure 4821: Authorization to TTN
  1. Now that you are logged in to the platform, the next step is to create an application. Click Create an application.
Figure 4822: Creating TTN application for your LoRaWAN devices
  1. To have an application registered, you need to input first the specific details and necessary information about your application then click Create application.
Figure 4823: Details of the TTN application
  1. If you had no error during the previous step, you should now be on the application console page. The next step is to add end-devices to your TTN application. LoRaWAN specification enforces that each end-device has to be personalized and activated. There are two options for registering devices depending on the activation mode you select. Activation can be done either via Over-The-Air-Activation (OTAA) or Activation-By-Personalization (ABP). This guide will show OTAA.
TTN OTAA Device Registration​
  1. Go to your application console to be able to register a device. To start adding an OTAA end-device, click + Add end device, as shown in Figure 35.
Figure 4824: Add end device
  1. To register the module, click first Manually then configure the activation method by selecting Over the air activation (OTAA) and compatible LoRaWAN version then click the Start button, as shown in Figure 36 and Figure 37.
Figure 4825: Manually register the device to TTN
Figure 4826: Device activation configuration
  1. Then you need to put a unique End device ID and EUIs (DevEUI and AppEUI), as shown in Figure 38. Check if your module has a DevEUI on the sticker or QR that you can scan then use this as the device unique DevEUI.

Optionally, you can add a more descriptive End device name and End device description about your device.

  1. After filling in all the details, click Network layer settings to proceed to the next step.
NOTE

It is advisable to use a meaningful end-device ID, end-device name, and end-device description that will match your device's purpose. The end-device ID rak-device is for illustration purposes only.

Figure 4827: OTAA Device Information
  1. The next step is to set up the Frequency plan, a compatible Regional Parameter version, and the LoRaWAN class supported. Then you can click Join settings.
Figure 4828: OTAA Configuration
  1. The last step in the registration of a new OTAA end-device is the configuration of the AppKey. To get the AppKey, you must click the generate button. Then click Add end device to finish your new device registration.
Figure 4829: OTAA AppKey generation and device registration

You should now be able to see the device on the TTN console after you fully register your device, as shown in Figure 41.

NOTE
  • The AppEUI, DevEUI, and AppKey are the parameters that you will need to activate your LoRaWAN end-device via OTAA. The AppKey is hidden by default for security reasons, but you can easily show it by clicking the show button. You can also copy the parameters quickly using the copy button.
  • The three OTAA parameters on the TTN device console are MSB by default.
  • These parameters are always accessible on the device console page, as shown in Figure 50.
Figure 4830: OTAA device successfully registered to TTN
Uploading LoRaWAN Example to RAK3372​

After a successful registration of the RAK3372 device on the LNS, you can now proceed with running the LoRaWAN OTAA demo application example.

  1. Launch the Arduino IDE and configure WisDuo RAK3172 Evaluation Board on board selection. See Figure 16.
  2. Connect the RAK3372 via UART and check RAK3372 COM Port. See Figure 17.
  3. Open the example code under RAK WisBlock RUI examples: File -> Examples -> RAK WisBlock RUI examples -> Example -> LoRaWan_OTAA.
Figure 4831: OTAA LoRaWAN application example
  1. In the example code, you need to modify the device EUI OTAA_DEVEUI, the application EUI OTAA_APPEUI, and the application key OTAA_APPKEY.
  • The OTAA_DEVEUI parameter should match the device EUI registered in your network server. Note that your RAK3372 module has a sticker with a QR code printed on it. You can use the QR code information to configure the OTAA_DEVEUI parameter. The OTAA_DEVEUI format is MSB first.
  // OTAA Device EUI MSB
#define OTAA_DEVEUI   {0x11, 0x33, 0x55, 0x77, 0x99, 0x22, 0x44, 0x66}
  • The OTAA_APPEUI parameter. This parameter should also be the same as the APPEUI in the network server you configured.
  // OTAA Application EUI MSB
#define OTAA_APPEUI   {0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x09}
  • Another important parameter to change is the application key OTAA_APPKEY. This parameter should also be the same as the APPKEY in the network server you configured. The OTAA_APPKEY format is MSB first.
// OTAA Application Key MSB
#define OTAA_APPKEY   {0x04, 0xFA, 0x4E, 0x62, 0x6E, 0xF5, 0xCF, 0x22, 0x7C, 0x96, 0x96, 0x01, 0x17, 0x62, 0x75, 0xC2}
Figure 4832: Configuring DEVEUI, APPEUI and APPKEY
  1. Depending on the Regional Band you selected, you might need to configure the sub-band of your RAK module to match the gateway and LoRaWAN network server. This is especially important for Regional Bands like US915, AU915, and CN470.

This guide uses EU868. However, if you use other regional bands, you need to update the band and possibly the channels. For example, if you use US915 and AU915, you also need to set up the channel mask using the mask.set API. Channels 8 to 15 are the most commonly used channels in the US915 and AU915 bands which corresponds to a mask equal to two.

Here's example on using US915 with OTAA_BAND equal to 5:

  if (!api.lorawan.band.set(OTAA_BAND)) {
    Serial.printf("LoRaWan OTAA - set band is incorrect! \r\n");
    return;
  }
  uint16_t maskBuff = 0x0002;
  if (!api.lorawan.mask.set(&maskBuff)) {
    Serial.printf("LoRaWan OTAA - set mask is incorrect! \r\n");
    return;
  }

NOTE

RAK3372 supports the following regions:

  • RAK_REGION_EU433 = 0
  • RAK_REGION_CN470 = 1
  • RAK_REGION_RU864 = 2
  • RAK_REGION_IN865 = 3
  • RAK_REGION_EU868 = 4
  • RAK_REGION_US915 = 5
  • RAK_REGION_AU915 = 6
  • RAK_REGION_KR920 = 7
  • RAK_REGION_AS923 = 8
  • RAK_REGION_AS923-2 = 9
  • RAK_REGION_AS923-3 = 10
  • RAK_REGION_AS923-4 = 11
NOTE
  1. Open the Tools Menu and select a COM port. COM28 is currently used.
Figure 4833: Select COM port
  1. The last step is to upload the code by clicking the Upload icon on Arduino IDE. Take note that you should select the right board and COM port.
Figure 4834: Uploading the code
  1. You should now be able to see the console logs using the serial monitor of Arduino IDE. Sometimes COM port will be disconnected, so you won't be able to see the terminal output immediately. You can reconnect the module or try to push the reset button to see the terminal output.
Figure 4835: Arduino serial monitor logs
  1. Check on the LoRaWAN network TTN console logs if your device has been successfully joined with the join-request and join-accept messages.
Figure 4836: TTN console log

Miscellaneous​

Upgrading the Firmware​

If you want to upgrade to the latest version of the firmware of the module, you can follow this section. The latest firmware can be found in the software section of RAK3172 Datasheet.

NOTE

What if the RAK3372 WisBlock Core module stops responding to AT commands and/or firmware updates?

You can recover your device by using the .hex file in the datasheet and uploading it using STM32CubeProgrammer. The guide on updating STM32 firmware using STM32CubeProgrammer can be found in the Learn section.

warning

Uploading the .hex file via STM32CubeProgrammer will erase all configured data on the device.

Firmware Upgrade Through UART2​

Minimum Hardware and Software Requirements​

Refer to the table for the minimum hardware and software required to perform the firmware upgrade via UART2:

Hardware/SoftwareRequirement
ComputerA Windows/Ubuntu/Mac computer
Firmware FileBin firmware file downloaded from the website
OthersA USB to TTL module
Firmware Upgrade Procedure​

Execute the following procedure to upgrade the firmware in Device Firmware Upgrade (DFU) mode through the UART2 interface.

NOTE

RAK3172 should automatically go to BOOT mode when the firmware is uploaded via RAK DFU Tool or WisToolBox.

  1. Download the latest application firmware of the RAK3172.

  2. Download the RAK Device Firmware Upgrade (DFU) tool.

  3. Connect the RAK3372 module with a computer through a USB to TTL.

  4. Open the Device Firmware Upgrade tool. Select the serial port and baud rate (115200) of the module and click the Select Port button.

NOTE

If your firmware upload always fails, check your current baud rate setting using the AT+BAUD=? command and use that baud rate value in the RAK DFU Tool. You can also check if you selected the right COM port.

Figure 4837: Device Firmware Upgrade Tool
  1. Select the application firmware file of the module with the suffix .bin.
Figure 4838: Select firmware
  1. Click the Upgrade button to upgrade the device. After the upgrade is complete, the RAK3372 will be ready to work with the new firmware.
Figure 4839: Firmware upgrading
Figure 4840: Upgrade successful