Skip to content

Python library reference

Jump to bottom
Ariel Rocholl edited this page Aug 14, 2024 · 4 revisions

Versions:

  • 1.26.1806.1

Description

RF Explorer library for Python uses the same class structure of the .NET library. However, class implementation and functionality is optimized for Python and simplified.

The library supports all type of RF Explorer devices, including

  • RF Explorer Handheld Spectrum Analyzer
  • RF Explorer Handheld Signal Generator
  • RF Explorer RackPro
  • RF Explorer IoT modules

The IoT modules are only supported in Raspberry Pi raspbian OS, whereas all other models are supported in Linux, Windows, MacOS and any Unix-like environment with Python 3.5 support.

Examples

As usually happens, playing with examples is the best way to understand how a technology works. RF Explorer for Python is no exception, so we suggest starting by looking into examples described on the wiki.

The list of available examples will grow over time so visit the wiki regularly for latest news.

Using the library

After installing the library with pip, you just need to do an

import RFExplorer

to include RF Explorer functionality in your python script.

The next step is to create an object of type RFECommunicator, which fully encapsulates all required functionality of the connected device. Using functions and properties of this object is all you need to fully automate the RF Explorer device.

The main task of the object is to connect to the required port, it can be USB for handheld devices or Raspberry Pi UART for IoT modules, but functionality is equivalent regardless of the port name.

UART port names differ among platforms, so these indications below may help:

  • Linux Raspberry Pi IoT: /dev/ttyAMA0
  • Linux USB: /dev/ttyUSBx where x is 0, 1, etc depending on how many devices are connected
  • Windows: COMx where x is 1, 2, etc depending on how many devices are connected
  • MacOS: /dev/tty.SLAB_USBtoUART may have an ordinal if more than one devices connected

However, if you have only one device connected, you can use None as argument of your RFECommunicator.ConnectPort call and the library will automatically determine port name for you, just as examples do. It can't get any easier than that.

After successfully connected to the device, you can send commands and receive data. Sending commands is easy, but for correct communication you need to regularly call to the processing loop. Check next section for more details.

To know more about all functions, properties and classes available in the RF Explorer Python library, please check class reference online.

Understanding the processing loop

The RF Explorer Python library implements a dedicated thread which works in the background, capturing all UART data and collecting the information in the assigned collections. For instance each time the RF Explorer device send a full sweep of data, the background thread receives than information and creates a new RFESweepData object and fills it with received data.

Therefore, pretty much all communication processing happens asynchronously and silently in the background.

However, the background thread cannot do certain RFECommunicator updates except by explicitly calling the RFECommunicator .ProcessReceivedString() function. Therefore, the python script must call this function regularly or, at the very least, before trying to use any data received from the device.

The implementation is very simple, as shown on examples: anytime you want to process later data received from the device, do a call to RFECommunicator.ProcessReceivedString(True) so everything processed by the background thread is correctly updated in the RFECommunicator object.

In the same line of thought: if you are expecting the device to deliver a specific data (such as new configuration, a new sweep, etc) you can create a while-loop calling the RFECommunicator.ProcessReceivedString(True) for as long as required by the loop to reach the condition.

   while(objRFE.ActiveModel == RFExplorer.RFE_Common.eModel.MODEL_NONE):
      objRFE.ProcessReceivedString(True)    #Process the received configuration

That code above would be a good example of how to wait for the device to return the model: The RFECommunicator is created as MODEL_NONE and, before actual configuration arrives as result of a call to RFECommunicator.SendCommand_RequestConfigData(), you cannot use most of the functions with an unknown model. It is good practice to wait till the actual model and current configuration is received before going any further in your code.

Clone this wiki locally