Common problems in WisBlock and LoRa® using VS Code

When you are developing hardware many things can go wrong. Actually, all things that can go wrong will go wrong, so in this short tutorial, we will teach you how to deal with common mistakes when using WisBlock in LoRa® projects. Some time ago we presented a simple project to communicate two WisBlock through a P2P communication, and measure the maximum range reached. This tutorial will use the same code and project, so if you missed it, download the code and visit the tutorial for background.

What do you need?

• 2 WisBlock Starter Kit

Or you can buy them separately:

• 2 WisBlock Core RAK4631
• 2 WisBlock Base RAK5005-O

These items are also available in:

• Helium Developer Kit

Step by Step

Hardware connections

• Assembling
• Antennas
• Battery and Solar Panel

Common Problems

• Interference
• Wrong Antennas Frequencies

Hardware Debugging tips

• Blinking LEDs

Software Programming

• LoRa® parameters settings and functions
• Debugging tools VS Code → Serial Port
• Summary

Hardware Connections

Incorrect connections can cause many errors. WisBlock was designed to avoid these errors since its elements are easy to connect. However, we want to give you some recommendations.

Note: In this tutorial, some tips will be presented to recognize common problems with WisBlock. But to know the step-by-step we recommend consulting the Getting Started tutorial or the LoRa® P2P tutorial. Also, you can review the official documentation of WisBlock Starter Kit.

Assembling

WisBlock depends on the correct assembly of its pieces. The main idea is to make sure that all the pieces are well assembled in their right slot. There are three main types of slots in the RAKwireless WisBlock Starter Kit:

WisBlock Core Connector (40 pins - Green color in Figure 1)

WisBlock Core is the main WisBlock microcontroller where all information is processed.

WisBlock Sensor Slot (24 pins - Red color in Figure 1)

The WisBlock ecosystem has a large number of sensors for various applications, all of them can use this type of slot.

WisBlock IO Slot (40 pins - Blue color in Figure 1)

Used for connecting IO general-purpose modules, ADC inputs and other communications.

Make sure that you are connecting each part that is used in the correct slot. Remember that each of the three slots is for specific use. After connecting, fix the blocks with the screws available in each product. As shown in Figure 2.

Antennas

WisBlock Starter Kit brings the possibility of connecting two antennas, one for BLE and another to connect a LoRa® antenna. Both antennas have a SMD connection. This connection ensures great performance, but be careful when connecting and disconnecting the antennas of your device.

In addition, the type of antenna to be connected is highlighted on a small label on the WisBlock Core RAK4631. Check this label and do not confuse them, as this could cause a loss of power in the transmission and not allow the maximum range of the LoRa® network.

Battery and solar panel

The connector for the battery is a JST PJR-2.2mm pitch female, so make sure you get the male connector with these specifications, and plug them properly as shown in Figure 5.

Warning! The maximum allowable voltage of the battery is 4.2V. The battery must be rechargeable because there is a system that recharge it while WisBlock is connected via USB connector. If you charge a non-rechargeable battery, it will cause damage to the device or a battery explosion.

In case you don't have the connector, you can connect the battery by soldering the pins for this purpose. As can be seen in figure 6.

To connect a solar panel, you need to use a 1.5mm ZHR male connector. Make sure the polarity is correct: the GND pin is on the edge of the board.

Note: Remember that the maximum voltage to connect a solar panel to WisBlock is 5V, connecting a higher voltage value will damage the device.

Common Problems

Interference

This is a common problem that damages the communication of the devices. To avoid it we will give you some tips to take into account:

1. Check if your device is on a non-metallic surface because the soldering elements could cause a short circuit. If you are working in an industrial environment, you must isolate your device to avoid electrical connection interference, avoid contact with water or other signals that may interfere with transmission. For this, you can use the enclosures that RAKwireless has for you

2. Check the correct functionality of the connectors and cables you are using, even the USB cable that is connected to the device and your computer. A correct connection could be shown through serial communications as you will see it in the software section, but for now, you can verify through hardware with simple items:

• In WisBlock you have three LEDs that can be lit to indicate that a specific line or function of your code is working. The red one is useful to check if WisBlock has the correct power supply, it is always on if WisBlock is connected to a power source; the green LED will light up when you are uploading firmware to your WisBlock Base and finally you have a blue LED to use in your projects.

3. A common mistake when connecting two devices is using a USB hub and connect both WisBlocks to it. You should check if there is no interference with the signals reaching the hub, and verify if you are using other items connected to the same port, such as Bluetooth devices, keyboards, etc.

Hardware Debugging Tips

The classic hardware debugging consists of turning on an LED in a specific segment of the program that we need to know if it is working. The code is like a data path and its mission is to make sure that the data arrives safely from the beginning to the destination. So, we put little signals to know that the data is going through there. Look at a small example:

void OnTxDone(void)
{
  digitalWrite(LED_BLUE, HIGH);
  Serial.println("OnTxDone");
  delay(100);
  digitalWrite(LED_BLUE, LOW);
  Radio.Rx(RX_TIMEOUT_VALUE);
  delay(5000);     
}

void OnRxDone(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr)
{
  digitalWrite(LED_GREEN, HIGH);
  Serial.println("OnRxDone");
  delay(100);
 digitalWrite(LED_GREEN, LOW);
  memcpy(RcvBuffer, payload, size);

  Serial.printf("RssiValue=%d dBm, SnrValue=%d\n", rssi, snr);

  for (int idx = 0; idx < size; idx++)
  {
    Serial.printf("%02X ", RcvBuffer[idx]);
  }
  Serial.println("");
  delay(100);
  Radio.Standby();
  Radio.SetCadParams(LORA_CAD_08_SYMBOL, LORA_SPREADING_FACTOR + 13, 10, LORA_CAD_ONLY, 0);
  Radio.StartCad(); 
}

This is a simple example of how to use a blinking led when you are sending or receiving data. In the first lines of the functions we are turning on a led for 10ms to show that the process is working. The two WisBlocks will show a visible signal as seen in Figure 10.

Connections for debugging communications

You can check the output for I2C or UART using the appropriate pins to measure communication. Holes for this purpose can be soldered or small measurement pins can be used to connect and receive this signal with a logic analyzer.

Software

For this point, you need to have installed VS Code and PlatformIO and the main libraries for running programs on WisBlock. If you don't know how it works, check out this tutorial. After installing these tools, the process to create a new LoRa® project is simple.

To add the libraries needed to compile the program, go to Libraries and search for the library name and then click on Add to Project.

In the pop-up window, select the project you want to add the library to.

Repeat the above process for the LoRa® library, and voila! If you are connecting two WisBlock using LoRa®, do this process for both codes. In that particular case Home and Traveler.

To make sure your libraries are installed, go to the platformio.ini file and check the following lines:

Correct use of Libraries

Defining the LoRa® parameters is the most important part of the code. These parameters ensure that data such as frequency, bandwidth, transmission power, among others. You can see the parameters and total values ​​in the official datasheet of the SX1262 transceiver.

// Define LoRa parameters
#define RF_FREQUENCY 915000000	// Hz
#define TX_OUTPUT_POWER 22		// dBm
#define LORA_BANDWIDTH 0		// [0: 125 kHz, 1: 250 kHz, 2: 500 kHz, 3: Reserved]
#define LORA_SPREADING_FACTOR 7 // [SF7..SF12]
#define LORA_CODINGRATE 1		// [1: 4/5, 2: 4/6,  3: 4/7,  4: 4/8]
#define LORA_PREAMBLE_LENGTH 8	// Same for Tx and Rx
#define LORA_SYMBOL_TIMEOUT 0	// Symbols
#define LORA_FIX_LENGTH_PAYLOAD_ON false
#define LORA_IQ_INVERSION_ON false
#define RX_TIMEOUT_VALUE 3000
#define TX_TIMEOUT_VALUE 3000

The parameters below will be needed to start the LoRa® transceiver and the appropriate functions for that.

Radio.Init(&RadioEvents);

// Set Radio channel
Radio.SetChannel(RF_FREQUENCY);

// Set Radio RX configuration
Radio.SetRxConfig(MODEM_LORA, LORA_BANDWIDTH, LORA_SPREADING_FACTOR,
	    LORA_CODINGRATE, 0, LORA_PREAMBLE_LENGTH,
	    LORA_SYMBOL_TIMEOUT, LORA_FIX_LENGTH_PAYLOAD_ON,
	    0, true, 0, 0, LORA_IQ_INVERSION_ON, true);

 // Set Radio TX configuration
 Radio.SetTxConfig(MODEM_LORA, TX_OUTPUT_POWER, 0, LORA_BANDWIDTH,
            LORA_SPREADING_FACTOR, LORA_CODINGRATE,
            LORA_PREAMBLE_LENGTH, LORA_FIX_LENGTH_PAYLOAD_ON,
            true, 0, 0, LORA_IQ_INVERSION_ON, TX_TIMEOUT_VALUE);

The installed libraries contain simple functions that are easy to use, with correct initialization of some parameters. The main functions of LoRaWAN® allow to send and receive data. This function works on events, that is, they are activated when an event is detected in the radio and executes the function associated with it. The send() function is not required to initialize in the Arduino IDE, but in Visual Studio Code it is.

// Function declarations
void OnRxDone(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr);
void OnRxTimeout(void);
void OnRxError(void);
void OnTxDone(void);
void OnTxTimeout(void);
void OnCadDone(bool cadResult);
void send();

// Initialize the Radio callbacks
RadioEvents.TxDone = OnTxDone;
RadioEvents.RxDone = OnRxDone;
RadioEvents.TxTimeout = OnTxTimeout;
RadioEvents.RxTimeout = OnRxTimeout;
RadioEvents.RxError = OnRxError;
RadioEvents.CadDone = OnCadDone;

The last recommendation is to be aware of the configuration with hardware and software. If you are using unidirectional communication, you only use RX functions in a single WisBlock and the TX functions in another. If you are using bidirectional communication, you must use the functions used for TX and RX in both WisBlocks. Sending data to the cloud will be presented in the next tutorials, so don't forget to subscribe to our official channel.

Be careful with the parameters, these must be defined according to the hardware that you want to use, especially the frequency. It must be defined according to the antenna you have and the region where you are developing your project. For more information, you can check your region on the RAKwireless official page.

Build and upload

Before compiling and uploading your code, make sure to add the following lines to the platformio.ini file:

Check that the port is the same where WisBlock is connected. Then you are ready to load the program.

Debugging Tools

The surefire way to debug your code is to use the serial monitor to print messages at every function or line of code you're on and testing. Let's go with an example:

void OnRxTimeout(void)
{
	Serial.println("OnRxTimeout");
	Radio.Rx(RX_TIMEOUT_VALUE);
}

This method works very well but sometimes you need to know what is happening. In a very long code, you need to know which part the microcontroller is executing at each moment, for that you can use the Trace Method, used in our previous tutorial and available for more information in the official repository on GitHub.

To use this library in VSCode, you need to add the library to projects that you can use.

This library includes three main functions. The first is TRACE(), to determine which line and functions the microcontroller is executing, the second is DUMP(variable) which can trace a variable value, no arrays or buffers are accepted, only single value variables. The last function is BREAK() which allows you to pause the execution of the code at a given line.

When replacing all the lines that use Serial.println() for debugging with the functions in the library, we get the following result:

Figure 21 shows another result you get when you use the trace method. At each moment the file, the function and some values ​​that the microcontroller is executing are shown.

Summary

• If you have problems programming your WisBlock make sure you have updated the latest version of the bootloader. You can do it by following the steps that we show you in this Hackster tutorial.
• Check that the connectors and cables used are in good condition and they are well connected.
• Check that all the parts are connected in the slots given for this use.
• Before programming your WisBlock, make sure the port to which it is connected. Check this in Start (Windows) > Device Manager, and in Ports, check the number of the port that is active.
• If you are programming a LoRa® application, configure your WisBlock according to the role being used, such as Receiver, Transmitter, or Transceiver, and accordingly review the necessary parameters. Check the tutorial and the code we have uploaded for LoRa® P2P communication.
• Finally, use the software and hardware tools that you have available in your WisBlock and in Visual Studio Code which was explained in this tutorial.

What’s next?

In this and the previous tutorials, we review the basics of WisBlock using software like Arduino and VS Code. In the following tutorials we cover the new way of programming developed for RAKwireless for all our users, RUI3. Then we will develop a complete project for real cases and uses, which you can implement. Leave us your questions and ideas on how we can improve this content and follow our official profile for more information and tutorials for RAKstars!