Library reference - RFExplorer/RFExplorer-IoT-for-Arduino GitHub Wiki

Versions:

  • 1.0.1611.1
  • 1.0.1612.1

Description

RF Explorer Library for Arduino allow an easy as well as powerful use of RF Explorer 3G+ IoT modules. We developed a native Arduino library organized in classes and functions. Using the Arduino library is intuitive and straightforward.

We recommend the examples listed below to better understand how to use the library for your own sketch code:

The implementation structure and layout follows the same pattern all standard Arduino sketch propose: use standard functions setup() and loop().

As usually, inside setup() you would configure all Arduino startup details, such as in/out pin configuration. In addition to that, the function should configure and initialize RF Explorer 3G+ IoT shield communication. In the same context, the main loop function would implement all recurring code to capture data from the RF module, such as get the signal peak from a scan.

Specifically for RF Explorer 3G+ IoT, using RFE_IoT_GetPeak example implemented in an Arduino Due, the expected sketch structure is as follows:

  • setup():

  • Initialize hardware and UART communications

  • Connect RF module MWSUB3G up to 115200bps

  • The Serial Monitor (UART0 using USB) configured at 57600bps

  • Initial call to requestConfig() required to receive RF module MWSUB3G configuration

  • loop():

  • Continuously scan the frequency spectrum so signal peak can be detected

  • For every received sweep, the Serial Monitor would display the power and frequency of the detected peak

Understanding the capture loop

Probably the most important concept to understand, for a correct sketch implementation, is the way communication flows between the RF Explorer 3G+ IoT and the Arduino sketch. The RF Explorer 3G+ IoT is sending data to the Arduino UART in realtime, and therefore is important for the Arduino code to be up to the task to handle this massive information flow.

There are two specific functions handling this capture loop implementation:

  • updateBuffer(): This function gets bytes captured by the Arduino UART and stores internally in a IoT library buffer. This is important to avoid Arduino UART overflow.
  • processReceivedString(): This function actively parse and process all IoT internally stored bytes and convert them into usable data and high level commands the library and the Arduino sketch can use.

Both functions must be called regularly inside the Arduino sketch loop() function. That is the only way to guarantee all information being transmitted by the RF module is correctly captured and processed. If these functions are not called with required recurrence, or if there is too much latency between calls, the information being transmitted by the RF module may be partially or totally lost.

Correct implementation of the capture loop

As described, every Arduino sketch using RF Explorer 3G+ IoT must call updateBuffer() and processReceivedString() regularly, see highlights 1 and 2 respectively in the image below.

The return value from processReceivedString() should be used to externally process received information, as depicted in highlighted block 3. This sketch processing code must be effective and fast, to minimize latency which could delay capture loop calls in the next iteration.

Any implemented error handling, data display, and data processing must be fast as shown in blocks 3 and 4.

Incorrect implementation of the capture loop

To make it more explicit how-not-to implement a capture loop, we can use the same example and simply add a delay to increase latency. In this new sample code, we introduce a delay(1000) to force Arduino to hold for 1 second before going back to the capture loop.

With this long delay in place, the Arduino UART will overload and lose bytes. The end result are communication errors between Arduino sketch and RF module, one possible output may look like this:

In this output example the Serial Monitor display a number of errors (Error 20) and did not complete any successful spectrum data capture. This is due to partial data lost in the UART. Note: more details on error codes section.

If your sketch run into errors like that listed before, the following suggestions may help to fix them easily.

Fixing capture loop errors:

  • Use simpler, faster code in your loop() function
  • Call the two capture loop functions in more than one place
  • Select lower communication baudrate so the RF module sends data at lower rate
  • Improve functionality of your loop() implementation by reporting minimal results only when required
  • Use functions setHold() and setRun() to temporarily hold communication with RF module

Note: If you need to measure run time of your code, consider using the micros() function from Arduino libraries, it helps to understand where the highest latency areas may be.

Table of contents

Class RFExplorer_3GP_IoT

Function void init()

Initialize necessary elements (communication, member variables...) en el RF Explorer 3G+ IoT. Call this function one time at the beginning.

Parameter Type Description
Return void -

Function void resetHardware()

Hardware restart to RF Explorer RFExplorer 3G+ IoT. 5 seconds recommended. It places Reset pin at low level for a certain time.

Parameter Type Description
Return void -

Function void changeBaudrate(uint32_t nbaudrate)

Change RF Explorer UART module communication baud rate. The change is immediate and it is lost after a reset.

Parameter Type Description
Return void -
nbaudrate uint32_t new baudrate for asynchronous UART communication. Available baud rates are (bps) 2400, 4800, 9600, 19200, 38400, 57600. For Arduino Due (and other ARM based boards) is possible to work up to 115200

Example:

        changeBaudrate(115200);

Function void changeNumberSteps(uint16_t nSteps)

Change the number of steps in frequency for optimum processing. The greater number of steps, the greater the RBW, but the longer processing time is required and more RAM is required to store all the steps. Recommended for Arduino Due - 512 points. Recommended for Seeeduino - 240 points. As a clarifying note, and for users who know and work with the RF Explorer family; Handheld devices have a fixed number of steps of 112.

Parameter Type Description
Return void -
nSteps uint16_t Number of steps for resolution

Example:

        changeNumberSteps(512);

Function void requestConfig()

Request RF Explorer command of configuration from RFExplorer 3G+ IoT. This command receives the current configuration of the unit.

Parameter Type Description
Return void -

Function void sendNewConfig(uint32_t nStartFreqKHZ, uint32_t nEndFreqKHZ)

Change the current settings for RF Explorer 3G + IoT. A start and stop frequency are set for spectrum analysis. It will change current configuration for RF. Internal Top and Bottom are set to 0dBm and -120dBm. RF Explorer 3G + IoT ignores these unit.

Parameter Type Description
Return void -
nStartFreqKHZ uint32_t Value of frequency span start in kHz (lower))
nStartFreqKHZ uint32_t Value of frequency span end in kHz (higher)

Example:

        sendNewConfig(1180000, 1200000);

Function void setHold()

Stop spectrum analyzer data dump.

Parameter Type Description
Return void -

Function void setRun()

Start the device if it was previously stopped.

Parameter Type Description
Return void -

Function void sleep()

Shutdown RF Explorer unit. It needs a resetHardware() to reactivate.

Parameter Type Description
Return void -

Function uint8_t updateBuffer()

Enter the values received by the serial port stored in a Circular Buffer.

Critical function: Update this circular buffer periodically to avoid loss of information.

Parameter Type Description
Return uint8_t Number of bytes reading

Function uint8_t processReceivedString()

Function that processes the different types of messages in RFExplorer that are stored in the Circular Buffer. It also manages error handling. .

Critical function. This method stores information in the RFEConfiguration class (last device configuration) and in the RFESweepData class (last set of valid data).

Parameter Type Description
Return uint8_t 0 if it is sucess. Look at Error Handling in other case

Function uint8_t getLastMessage()

Returns the message type of the last process performed in processReceivedString (). It therefore identifies the type of information received to act in each case.

Valid types of messages are constants such as: _CONFIG_MESSAGE / _SWEEP_MESSAGE / _MODEL_MESSAGE / _UNKNOWN_MESSAGE / _ERROR_MESSAGE / _SERIALNUMBER_MESSAGE

For more information Messages

Parameter Type Description
Return uint8_t 0 if it is sucess

Function boolean isValid()

A function that determines whether the configuration and data received from the 3G + have a correct format that allows the user to perform operations.

Parameter Type Description
Return boolean 0 if it is sucess

Function uint8_t getPeak(uint32_t *pFreqKHZ, int16_t *pMaxDBM)

It obtains the maximum value of the data amplitude and the corresponding frequency according to the configuration of the device.

Parameter Type Description
Return uint8_t 0 if it is sucess
pFreqKHZ uint32_t* Pointer to frequency in KHz of maximum value
pMaxDBM uint32_t* Pointer to max value in dBm

Example:

        if (g_objRF.getPeak(&nFreqPeakKHZ, &nPeakDBM) ==_RFE_SUCCESS)           
        {
            g_objRF.getMonitorSerial().print(nFreqPeakKHZ);
            g_objRF.getMonitorSerial().print(" KHz to ");
            g_objRF.getMonitorSerial().print(nPeakDBM);
            g_objRF.getMonitorSerial().println(" dBm"); 
        }

Function RFEConfiguration* getConfiguration()

Returns the internal object for use of methods and properties from class RFEConfiguration . This object contains the last device configuration. RFExplorer_3GP_IoT :: isValid () must be consulted to ensure the validity of the data before attempting to use them.

Parameter Type Description
Return RFEConfiguration* Pointer to object class RFEConfiguration

Example:

        if ((g_objRF.getLastMessage() == _CONFIG_MESSAGE)) 
        {
            g_objRF.getMonitorSerial().print("StartKHz: "); 
            g_objRF.getMonitorSerial().println(g_objRF.getConfiguration()->getStartKHZ());
        }

Function RFESweepData* getSweepData()

Returns the internal object for use of methods and properties from class RFESweepData. This object contains the last sweep captured. RFExplorer_3GP_IoT :: isValid () must be consulted to ensure the validity of the data before attempting to use them.

Parameter Type Description
Return RFESweepData* Pointer to object class RFESweepData

Example:

        if((g_objRF.getLastMessage() == _SWEEP_MESSAGE) && g_objRF.isValid()) 
        {
            g_objRF.getMonitorSerial().print("StartKHz: "); 
            g_objRF.getMonitorSerial().println(g_objRF.getSweepData()->getStartKHZ());
        }

Function getMonitorSerial()

Access to the internal object. Used to do prints in the Serial Monitor of the different types of Serial that Arduino owns. In the case of Arduino Due is encapsulated HardwareSerial and in the case of Seeeduino is encapsulated SoftwareSerial.

For more information look at: https://www.arduino.cc/en/Reference/Serial

Parameter Type Description
Return HardwareSerial& Encapsulate object Serial3 if it´s Arduino Due
Return SoftwareSerial& Encapsulate object Software Serial if it´s Arduino Small Factor

Example:

            int nFreqPeakKHZ = 2462000;
            g_objRF.getMonitorSerial().print(nFreqPeakKHZ);
            g_objRF.getMonitorSerial().println(" KHz");

Class RFEConfiguration

Function uint32_t getStartKHZ()

Get value of frequency span start (lower) of the last received configuration

Parameter Type Description
Return uint32_t Initial frequency in KHz

Function uint32_t getEndKHZ()

Get Value of frequency span end (higher) of the last received configuration

Parameter Type Description
Return uint32_t Stop frequency in KHz

Function uint32_t getStepHZ()

Get Value of frequency of sample step of the last received configuration

Parameter Type Description
Return uint32_t Step frequency in Hz

Function uint16_t getFreqSpectrumSteps()

Gets the total steps of the last received configuration.

Parameter Type Description
Return uint16_t Number of total steps

Function eMode getModeRFE()

Get Mode of codified values

Parameter Type Description
Return eMode Mode

Function uint32_t getMinFreqKHZ()

Get Min frequency value for the selected RF circuit and mode

Parameter Type Description
Return uint32_t Min frequency in KHz

Función uint32_t getMaxFreqKHZ()

Get Max frequency value for the selected RF circuit and mode

Parameter Type Description
Return uint32_t Max frequency in KHz

Función uint32_t getRBWKHZ()

Get Resolution Bandwidth currently selected

Parameter Type Description
Return uint32_t Frequency in KHz of RBW

Function uint32_t getMaxSpanKHZ()

Get Max supported Span value for the selected RF circuit and mode

Parameter Type Description
Return uint32_t Initial frequency in KHz

Function uint16_t getOffset_dB()

Get OffsetDB manually specified in the unit, including sign

Parameter Type Description
Return uint16_t Offset value in dB

Function eCalculator getCalculatorRFE()

Get Mode use to process results

Parameter Type Description
Return eCalculator Process Mode. Possible values: 0=NORMAL, 1=MAX, 2=AVG, 3=OVERWRITE, 4=MAX_HOLD

Function eModel getMainBoardModel()

Get Codified values for devices RF Explorer. The value returned by the 3G + IoT will be 5 corresponding to the module MWSUB3G

Parameter Type Description
Return eModel Model

Function char* getRFExplorerFirmware()

Get Standard Version Firmware format xx.yy, may change format for betas or custom versions

Parameter Type Description
Return char* Pointer to first element in string that contains number of firmware version

Function char* getRFExplorerSerialNumber()

Get Serial Number of devices RF Explorer

Parameter Type Description
Return char* Pointer to first element in string that form Serial Number

Class RFESweepData

Function uint32_t getFrequencyKHZ(uint16_t nStep)

Returns value in frequency given a certain step.

Parameter Type Description
Return uint32_t Frequency in KHz
nStep int16_t Number of Step

Function int16_t getAmplitudeDBM(uint16_t nStep)

Returns value in amplitude given a certain step.

Parameter Type Description
Return int16_t Amplitude in dBm
nStep int16_t Number of Step

Function uint16_t_t getPeakStep()

Parameter Type Description
Return uint16_t Number of Step where max value of amplitude are founded

Function uint32_t getStartFrequencyKHZ()

Gets the initial value of the frequency corresponding to the last data sweep.

Parameter Type Description
Return uint32_t Initial Frequency in KHz

Function uint32_t getEndFrequencyKHZ()

Gets stop value of the frequency corresponding to the last data sweep.

Parameter Type Description
Return uint32_t Stop Frequency in KHz

Function uint32_t getStepFrequencyHZ()

Gets frequency corresponding to the step size of the last data sweep.

Parameter Type Description
Return uint32_t Frequency in Hz of step

Function uint16_t getTotalSteps()

Get number ot total points of the last data sweep.

Parameter Type Description
Return uint16_t Number of steps

Messages RFExplorer_3GP_IoT

Number Message Code Message Explanation
1 _CONFIG_MESSAGE Message RFEConfiguration
2 _SWEEP_MESSAGE Message RFESweepData
3 _MODEL_MESSAGE Model of RFExplorer
4 _UNKNOWN_MESSAGE Message not processed and unknown
5 _ERROR_MESSAGE Error. Look at section error handling
6 _SERIALNUMBER_MESSAGE Serial Number RFExplorer 3G+ IoT

Error Handling RFExplorer_3GP_IoT

Number Error Error Code Function
0 _RFE_SUCCESS Process correct.
1 _RFE_ERROR General Error. Not used.
3 _RFE_ERROR_UNEXPECTED_CHARACTER Character received is not correct. The full message is discarded..
4 _RFE_ERROR_UNEXPECTED_SIZE Message size is not suitable.
5 _RFE_ERROR_STRING_OVERFLOW The memory storage is saturated. It is a fatal error.
10 _RFE_ERROR_CONFIG RFEConfiguration is incorrect.
11 _RFE_ERROR_SWEEP_BAD_CONFIG RFESweepData is incorrect because RFEConfiguration previous is incorrect. Method processReceivedString() previous returns _RFE_ERROR_CONFIG and RFESweepData are discarded.
12 _RFE_ERROR_DEVICE_INCORRECT Device is not a RF Explorer 3G+ IoT para Arduino.
20 _RFE_IGNORE It is not an error. It is information processor. It has not received enough characters to process a complete message.
21 _RFE_NOT_MESSAGE Message process is unknown for library.