-
Notifications
You must be signed in to change notification settings - Fork 2
Library reference
Versions:
- 1.0.1611.1
- 1.0.1612.1
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
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.
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.
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()
andsetRun()
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.
- Class RFExplorer_3GP_IoT
- Class RFEConfiguration
- Class RFESweepData
- Messages of RFExplorer_3GP_IoT
- Error Handling of RFExplorer_3GP_IoT
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 | - |
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 | - |
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);
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);
Request RF Explorer command of configuration from RFExplorer 3G+ IoT. This command receives the current configuration of the unit.
Parameter | Type | Description |
---|---|---|
Return | void | - |
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);
Stop spectrum analyzer data dump.
Parameter | Type | Description |
---|---|---|
Return | void | - |
Start the device if it was previously stopped.
Parameter | Type | Description |
---|---|---|
Return | void | - |
Shutdown RF Explorer unit. It needs a resetHardware() to reactivate.
Parameter | Type | Description |
---|---|---|
Return | void | - |
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 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 |
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 |
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 |
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");
}
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());
}
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());
}
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");
Get value of frequency span start (lower) of the last received configuration
Parameter | Type | Description |
---|---|---|
Return | uint32_t | Initial frequency in KHz |
Get Value of frequency span end (higher) of the last received configuration
Parameter | Type | Description |
---|---|---|
Return | uint32_t | Stop frequency in KHz |
Get Value of frequency of sample step of the last received configuration
Parameter | Type | Description |
---|---|---|
Return | uint32_t | Step frequency in Hz |
Gets the total steps of the last received configuration.
Parameter | Type | Description |
---|---|---|
Return | uint16_t | Number of total steps |
Get Mode of codified values
Parameter | Type | Description |
---|---|---|
Return | eMode | Mode |
Get Min frequency value for the selected RF circuit and mode
Parameter | Type | Description |
---|---|---|
Return | uint32_t | Min frequency in KHz |
Get Max frequency value for the selected RF circuit and mode
Parameter | Type | Description |
---|---|---|
Return | uint32_t | Max frequency in KHz |
Get Resolution Bandwidth currently selected
Parameter | Type | Description |
---|---|---|
Return | uint32_t | Frequency in KHz of RBW |
Get Max supported Span value for the selected RF circuit and mode
Parameter | Type | Description |
---|---|---|
Return | uint32_t | Initial frequency in KHz |
Get OffsetDB manually specified in the unit, including sign
Parameter | Type | Description |
---|---|---|
Return | uint16_t | Offset value in dB |
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 |
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 |
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 |
Get Serial Number of devices RF Explorer
Parameter | Type | Description |
---|---|---|
Return | char* | Pointer to first element in string that form Serial Number |
Returns value in frequency given a certain step.
Parameter | Type | Description |
---|---|---|
Return | uint32_t | Frequency in KHz |
nStep | int16_t | Number of Step |
Returns value in amplitude given a certain step.
Parameter | Type | Description |
---|---|---|
Return | int16_t | Amplitude in dBm |
nStep | int16_t | Number of Step |
Parameter | Type | Description |
---|---|---|
Return | uint16_t | Number of Step where max value of amplitude are founded |
Gets the initial value of the frequency corresponding to the last data sweep.
Parameter | Type | Description |
---|---|---|
Return | uint32_t | Initial Frequency in KHz |
Gets stop value of the frequency corresponding to the last data sweep.
Parameter | Type | Description |
---|---|---|
Return | uint32_t | Stop Frequency in KHz |
Gets frequency corresponding to the step size of the last data sweep.
Parameter | Type | Description |
---|---|---|
Return | uint32_t | Frequency in Hz of step |
Get number ot total points of the last data sweep.
Parameter | Type | Description |
---|---|---|
Return | uint16_t | Number of steps |
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 |
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. |