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

Referencia de la librería RF Explorer IoT para Arduino

Versiones:

  • 1.0.1611.1
  • 1.0.1612.1

Descripción

La librería RF Explorer IoT para Arduino ha sido creada para utilizar toda la potencia de los módulos RF Explorer IoT en el ecosistema de Arduino. Es una librería nativa, totalmente documentada y, organizada en clases y funciones. El uso en Arduino es intuitivo y sencillo.

Recomendamos los siguientes ejemplos para entender mejor el uso de la librería.

La estructura de funcionamiento sigue el mismo sistema que todos los sketch para Arduino: el uso de las funciones estándar setup() y loop().

Tradicionalmente, en setup() se realiza la configuración del Arduino, por ejemplo, se dice que pines son de entrada y cuales son de salida. En nuestro caso particular se configura el módulo RF Explorer 3G+ IoT. Por otro lado, el loop es el código que se estará ejecutando continuamente, por ejemplo, obteniendo el máximo de una señal.

Para el caso específico de la librería RF Explorer 3G+ IoT y usando como base el ejemplo RFE_IoT_GetPeak en un Arduino Due, la estructura del sketch es la siguiente:

  • setup():

  • Inicializa el Hardware y las comunicaciones UART

  • El módulo MWSUB3G se conecta a 115200bps

  • El Monitor Serial (UART0 a través del Puerto USB) se configura a 57600bps

  • Se llama la función requestConfig() para recibir la configuración del módulo MWSUB3G

  • loop():

  • Escanea continuamente el espectro de frecuencia para detectar el pico de señal

  • Cada vez que se recibe un escaneo (sweep) el Serial Monitor mostrará el máximo de potencia de la señal así como la frecuencia a la que se encontró dicho máximo

Descripción del bucle de captura

Probablemente el aspecto más importante de entender es, el ciclo de captura de datos de manera continua del módulo analizador RF Explorer 3G+ IoT y el sketch de Arduino. El RF Explorer 3G + IoT envía datos a la UART de Arduino en tiempo real, por lo que es importante que el código de Arduino esté correctamente programado para realizar la tarea de manejar este flujo masivo de información.

Las dos funciones que gestionan la captura de información entre el módulo RF y el sketch de Arduino son:

  • updateBuffer(): Esta función obtiene los bytes capturados por la UART de Arduino y los almacena internamente en el buffer interno de la librería IoT. Esta función es importante para evitar el desbordamiento de la UART de Arduino.
  • processReceivedString(): Esta función procesa todos los bytes almacenados internamente y los convierte en los datos y comandos de alto nivel que puede usar el sketch de Arduino.

Ambas funciones descritas arriba deben ser ejecutadas periódicamente en la función loop() del Sketch, para asegurarnos de que toda la información transmitida por el módulo RF es correctamente capturada y procesada. Si dichas funciones no son llamadas con la suficiente regularidad, la información transmitida por el módulo puede perderse total o parcialmente.

Implementación correcta del bucle de captura en un Sketch

En cualquier sketch de Arduino en el que se utilice RF Explorer 3G+ IoT se deben realizar llamadas frecuentes tanto a updateBuffer() (número 1 en la imagen siguiente) como a processReceivedString() (número 2 en la imagen). Estrictamente en ése orden.

El resultado devuelto por processReceivedString() se puede utilizar para procesar externamente la información, como se muestra en el bloque 3 de la imagen. El código utilizado en el bucle debe ser rápido y sencillo, para evitar que se produzcan demoras que puedan ocasionar la pérdida de información transmitida por el módulo RF.

La gestión de errores, presentación de información, etc debe ser rápida como se muestra en los bloques 3 y 4.

Ejemplo de Implementación incorrecta

Para aclarar más el concepto de bucle de captura, podemos utilizar la sencilla modificación mostrada en la imagen a continuación. En dicho ejemplo, se ha introducido un delay(1000) de forma que el bucle de captura tardará un segundo completo en volver a gestionar los bytes capturados por la UART.

Con este tipo de retrasos, la UART normalmente se desborda y algunos bytes se perderán, produciéndose errores de comunicación con el módulo RF y corrompiendo los datos. Un ejemplo de salida en un código como el de arriba podría ser como sigue:

En esta imagen del Serial Monitor podemos ver que, tras los caracteres de inicio de programa, aparecen mensajes de “Error: 20” y ninguno de procesamiento del espectro. Si consultamos el apartado Manejo de errores veremos que es un RFE_IGNORE que significa que el dispositivo se encuentra esperando para obtener más información de una cabecera cortada.

Como solucionar errores en el bucle de captura:

  • Utilizar un código sin retrasos ni esperas activas (procesamiento mas rápido)
  • Llame a las funciones de captura en más de una ocasión.
  • Seleccionar baudrates de menor velocidad
  • Mejorar el rendimiento del sketch
  • Detener temporalmente la comunicación con el módulo RF usando funciones setHold() y setRun()

Nota: Para el tiempo de monitorización en su programa utilice la función micros() de la referencia de lenguaje Arduino. Esta función devuelve el número de microsegundos desde que la placa Arduino empezó a ejecutar el programa, por tanto puede ser utilizada para diagnosticar tiempos de ejecución.

Lista de contenidos de clases

Class RFExplorer_3GP_IoT

Función void init()

Inicializa los elementos necesarios (comunicación, variables miembro...) en el RF Explorer 3G+ IoT. Llame a esta función una vez. Siempre al principio.

Parámetro Tipo Descripción
Retorno void -

Función void resetHardware()

Coloca el pin de Reset de RFExplorer 3G+ IoT a nivel bajo durante un tiempo determinado. Se recomiendan 5 segundos. Provoca un reinicio hardware en el módulo del 3G+.

Parámetro Tipo Descripción
Retorno void -

Función void changeBaudrate(uint32_t nbaudrate)

Cambia la velocidad de comunicación de RF Explorer con la UART principal. El cambio es inmediato y se pierde con un reset.

Parámetro Tipo Descripción
Retorno void -
nbaudrate uint32_t Nueva velocidad (bps) para la comunicación asíncrona con la UART. Las velocidades de transmisión disponibles para Arduinos de 8 bit (como Seeeduino) son: 2400, 4800, 9600, 19200, 38400, 57600. Para Arduino Due (u otros modelos basados en ARM) es posible alcanzar una velocidad de 115200

Ejemplo:

        changeBaudrate(115200);

Función void changeNumberSteps(uint16_t nSteps)

Cambia el número de pasos en frecuencia para un procesamiento óptimo. A mayor número de pasos, mayor RBW pero en contraposición es necesario mayor tiempo de procesamiento y se necesita mayor RAM para almacenar todos los pasos. Recomendado para Arduino Due - 512 puntos. Recomendado para Seeeduino - 240 puntos. Como nota aclaratoria, y para los usuarios que conocen y trabajan con la familia RF Explorer, los dispositivos Handheld poseen un número de pasos fijo de 112.

Parámetro Tipo Descripción
Retorno void -
nSteps uint16_t Numero de puntos para determinar la resolución en frecuencia

Ejemplo:

        changeNumberSteps(512);

Función void requestConfig()

Comando de petición de configuración en RF Explorer 3G+ IoT. Con este comando se recibe la configuración actual de la unidad.

Parámetro Tipo Descripción
Retorno void -

Función void sendNewConfig(uint32_t nStartFreqKHZ, uint32_t nEndFreqKHZ)

Cambiar la configuración actual para RF Explorer 3G+ IoT. Se establece una frecuencia de inicio y otra de parada para el análisis de espectro. Los valores de potencia se ajustan a 0dBm y -120dBm. RF Explorer 3G+ IoT ignora estas unidades.

Parámetro Tipo Descripción
Retorno void -
nStartFreqKHZ uint32_t Valor de inicio del intervalo de frecuencia en kHz (inferior)
nStartFreqKHZ uint32_t Último valor del intervalo de frecuencia en kHz (más alto)

Ejemplo:

        sendNewConfig(1180000, 1200000);

Función void setHold()

Detiene el volcado de datos del analizador de espectro.

Parámetro Tipo Descripción
Retorno void -

Función void setRun()

Inicia el dispositivo si se ha detenido previamente.

Parámetro Tipo Descripción
Retorno void -

Función void sleep()

Apaga la unidad RF Explorer 3G+ IoT. Necesita un resetHardware() para reactivarse.

Parámetro Tipo Descripción
Retorno void -

Función uint8_t updateBuffer()

Introduce los valores recibidos por el puerto serie almacenándolos en un Buffer Circular.

Función crítica: Actualizar este buffer circular periódicamente para evitar la pérdida de información.

Parámetro Tipo Descripción
Retorno uint8_t Número de bytes leídos en el último uso

Función uint8_t processReceivedString()

Función que procesa los diferentes tipos de Mensajes en RFExplorer que se almacenan en el Buffer Circular. Además gestiona el manejo de errores.

Función crítica. Este método almacena información en la clase RFEConfiguration (última configuración del dispositivo) y en la clase RFESweepData (último conjunto de datos válidos).

Parámetro Tipo Descripción
Retorno uint8_t 0 si es posible procesar. Ver Manejo de errores en otro caso

Función uint8_t getLastMessage()

Devuelve el tipo de mensaje del último proceso realizado en processReceivedString(). Identifica por tanto el tipo de información recibida para actuar en cada caso.

Los tipos válidos de mensajes son constantes como: _CONFIG_MESSAGE / _SWEEP_MESSAGE / _MODEL_MESSAGE / _UNKNOWN_MESSAGE/_ERROR_MESSAGE / _SERIALNUMBER_MESSAGE

Puede ampliar información en el apartado Tipos de Mensajes

Parámetro Tipo Descripción
Retorno uint8_t 0 si es éxito

Función boolean isValid()

Función que determina si la configuración y los datos recibidos del 3G+ tienen un formato correcto que permite al usuario realizar operaciones.

Parámetro Tipo Descripción
Retorno boolean 0 si es correcto

Función uint8_t getPeak(uint32_t *pFreqKHZ, int16_t *pMaxDBM)

Obtiene el valor máximo de la amplitud de datos y la frecuencia correspondiente de acuerdo a la configuración del dispositivo.

Parámetro Tipo Descripción
Retorno uint8_t 0 si es éxito
pFreqKHZ uint32_t* Puntero a la frecuencia de almacenamiento en KHz del valor máximo
pMaxDBM uint32_t* Puntero al valor máximo de almacenamiento en dBm

Ejemplo:

        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"); 
        }

Función RFEConfiguration* getConfiguration()

Devuelve el objeto RFEConfiguration interno para uso de métodos y propiedades. Este objeto contiene la última configuración del dispositivo. Debe consultarse RFExplorer_3GP_IoT::isValid() para asegurar la validez de los datos antes de intentar usarlos.

Parámetro Tipo Descripción
Retorno RFEConfiguration* Puntero al objeto de la clase RFEConfiguration

Ejemplo:

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

Función RFESweepData* getSweepData()

Devuelve el objeto RFESweepData interno para uso de métodos y propiedades. Este objeto contiene el último sweep capturado, pero debe consultarse RFExplorer_3GP_IoT::isValid() para asegurar la validez de los datos antes de intentar usarlos.

Parámetro Tipo Descripción
Retorno RFESweepData* Puntero al objeto de la clase RFESweepData

Ejemplo:

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

Función getMonitorSerial()

Acceso al objeto interno. Utilizado para realizar prints en el Serial Monitor de los distintos tipos de Serial que posee Arduino. En el caso del Arduino Due se encapsula HardwareSerial y en el caso de Seeeduino se encapsula SoftwareSerial.

Para más información consulte la referencia https://www.arduino.cc/en/Reference/Serial

Parámetro Tipo Descripción
Retorno HardwareSerial& Encapsula el objeto Serial3 si es Arduino Due
Retorno SoftwareSerial& Encapsula el objeto Software Serial si es Arduino Small Factor

Ejemplo:

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

Class RFEConfiguration

Función uint32_t getStartKHZ()

Obtiene el valor inicial de frecuencia de la última configuración recibida.

Parámetro Tipo Descripción
Retorno uint32_t Frecuencia inicial en KHz

Función uint32_t getEndKHZ()

Obtiene el valor final de la frecuencia de la última configuración recibida.

Parámetro Tipo Descripción
Retorno uint32_t Frecuencia final en KHz

Función uint32_t getStepHZ()

Obtiene la frecuencia correspondiente al tamaño del paso de la última configuración recibida.

Parámetro Tipo Descripción
Retorno uint32_t Frecuencia en Hz del paso en frecuencia

Función uint16_t getFreqSpectrumSteps()

Obtiene el número total de pasos de la última configuración recibida.

Parámetro Tipo Descripción
Retorno uint16_t Número total de pasos

Función eMode getModeRFE()

Obtiene el modo de funcionamiento del dispositivo.

Parámetro Tipo Descripción
Retorno eMode Modo de funcionamiento. Valores posibles del enumerado: SPECTRUM_ANALYZER:0, RF_GENERATOR:1, WIFI_ANALYZER:2, UNKNOWN:255

Función uint32_t getMinFreqKHZ()

Obtiene el valor mínimo de frecuencia que soporta el dispositivo 3G+ IoT.

Parámetro Tipo Descripción
Retorno uint32_t Valor mínimo de frecuencia en KHz del dispositivo

Función uint32_t getMaxFreqKHZ()

Obtiene el valor máximo de frecuencia que soporta el dispositivo 3G+ IoT.

Parámetro Tipo Descripción
Retorno uint32_t Valor máximo de frecuencia en KHz del dispositivo

Función uint32_t getRBWKHZ()

Obtiene el valor de Resolution Bandwith que está actualmente seleccionada.

Parámetro Tipo Descripción
Retorno uint32_t Frecuencia en KHz del RBW

Función uint32_t getMaxSpanKHZ()

Obtiene el valor máximo de Span para el dispositivo 3G+ IoT.

Parámetro Tipo Descripción
Retorno uint32_t Frecuencia en KHz del paso en frecuencia

Función uint16_t getOffset_dB()

Obtiene el valor de offset seleccionado en la unidad.

Parámetro Tipo Descripción
Retorno uint16_t Valor de offset en dB

Función eCalculator getCalculatorRFE()

Obtiene el modo usado en procesar resultados.

Parámetro Tipo Descripción
Retorno eCalculator Modo usado para procesar. Valores posibles: 0=NORMAL, 1=MAX, 2=AVG, 3=OVERWRITE, 4=MAX_HOLD

Función eModel getMainBoardModel()

Obtiene el valor codificado para los dispositivos RF Explorer.

El valor devuelto por el 3G+ IoT será 5 correspondiente al módulo MWSUB3G

Parámetro Tipo Descripción
Retorno eModel Modelo RF Explorer. Valores establecidos: 433M:0, 868M:1, 915M:2, WSUB1G:3, 2.4G:4, WSUB3G:5

|

Función char* getRFExplorerFirmware()

Obtiene el valor del firmware utilizado por la placa 3G+.

Parámetro Tipo Descripción
Retorno uint16_t Puntero al primer elemento de la cadena de caracteres que indica el número de versión

Función char* getRFExplorerSerialNumber()

Obtiene el número de identificación del dispositivo RF Explorer.

Parámetro Tipo Descripción
Retorno char* Puntero al primer elemento de la cadena de caracteres que forma el Serial Number

Class RFESweepData

Función uint32_t getFrequencyKHZ(uint16_t nStep)

Devuelve la frecuencia correspondiente a un determinado paso del RFESWeepData.

Parámetro Tipo Descripción
Retorno uint32_t Frecuencia en KHz
nStep int16_t Número de paso

Función int16_t getAmplitudeDBM(uint16_t nStep)

Devuelve la amplitud correspondiente a un determinado paso del RFESWeepData.

Parámetro Tipo Descripción
Retorno int16_t Amplitud en dBm
nStep int16_t Número de paso

Función uint16_t_t getPeakStep()

Devuelve el step del mayor valor de amplitud encontrado.

Parámetro Tipo Descripción
Retorno uint16_t Número de paso donde se haya el mayor valor en amplitud

Función uint32_t getStartFrequencyKHZ()

Obtiene el valor inicial de la frecuencia correspondiente al último sweep de datos.

Parámetro Tipo Descripción
Retorno uint32_t Frecuencia inicial en KHz

Función uint32_t getEndFrequencyKHZ()

Obtiene el valor final de la frecuencia correspondiente al último sweep de datos.

Parámetro Tipo Descripción
Retorno uint32_t Frecuencia final en KHz

Función uint32_t getStepFrequencyHZ()

Obtiene la frecuencia correspondiente al tamaño del paso del último sweep de datos.

Parámetro Tipo Descripción
Retorno uint32_t Frecuencia en Hz del paso en frecuencia

Función uint16_t getTotalSteps()

Obtiene el número total de pasos del último sweep de datos.

Parámetro Tipo Descripción
Retorno uint16_t Número total de pasos

Tipos de Mensajes RFExplorer_3GP_IoT

Número de Mensaje Código de mensaje Explicación
1 _CONFIG_MESSAGE Mensaje RFEConfiguration
2 _SWEEP_MESSAGE Mensaje RFESweepData
3 _MODEL_MESSAGE Modelo de RFExplorer
4 _UNKNOWN_MESSAGE Mensaje no procesado y desconocido
5 _ERROR_MESSAGE Error. Mirar sección manejo de errores
6 _SERIALNUMBER_MESSAGE Serial Number RFExplorer 3G+ IoT

Manejo de Errores RFExplorer_3GP_IoT

Número de Error Código de Error Función
0 _RFE_SUCCESS Procesamiento correcto.
1 _RFE_ERROR Error General. No usado.
3 _RFE_ERROR_UNEXPECTED_CHARACTER El carácter recibido no es correcto. El mensaje es descartado.
4 _RFE_ERROR_UNEXPECTED_SIZE El tamaño del mensaje no es adecuado.
5 _RFE_ERROR_STRING_OVERFLOW El almacenamiento de memoria está saturado. Es un error crítico.
10 _RFE_ERROR_CONFIG RFEConfiguration es incorrecto.
11 _RFE_ERROR_SWEEP_BAD_CONFIG RFESweepData es incorrecto porque el RFEConfiguration previo es incorrecto. El método previo processReceivedString() devuelve _RFE_ERROR_CONFIG y RFESweepData es totalmente descartado.
12 _RFE_ERROR_DEVICE_INCORRECT El dispositivo no es un RF Explorer 3G+ IoT para Arduino.
20 _RFE_IGNORE No es un error, es información de procesamiento. Significa que no se han recibido suficientes bytes para finalizar el tratamiento de un mensaje.
21 _RFE_NOT_MESSAGE El mensaje que se intenta procesar no es reconocido por la librería.