Example: Software-defined radio

This example uses software-defined radio as an example of edge processing. With software-designed radio, you can send raw data across the full radio spectrum to a cloud server for processing. The edge node processes the data locally and then sends lower volumes of higher value data to a cloud processing service for further processing.

software-defined radio (SDR) receives radio signals by using the digital circuitry in a computer CPU to handle the work to require a set of specialized analog circuitry. That analog circuitry is usually restricted by the breadth of radio spectrum it can receive. An analog radio receiver built to receive FM radio stations, for example, can't receive radio signals from anywhere else on the radio spectrum. Software-defined radio can access large portions of the spectrum.

Before you begin

Ensure that your system meets the following requirements:

Procedure

  1. Configure a kernel module to support your software-defined radio hardware. You must manually configure this module. Docker containers can establish a different distribution of Linux in their contexts, but the container cannot install kernel modules. Complete the following steps to configure this module:

    1. As a root user, create a file that is named /etc/modprobe.d/rtlsdr.conf.

      sudo nano /etc/modprobe.d/rtlsdr.conf

    2. Add the following lines to the file:

      blacklist rtl2830
blacklist rtl2832
blacklist dvb_usb_rtl28xxu

    3. Save the file and then restart before you continue:

      sudo reboot

  2. Register your device. To register your device for the software-defined radio pattern, use the IBM pattern that is named, sdr2msghub. You require a userinput.json file like the one shown in the following code snippet. Create this file by copying the following content into the file exactly. Name your file sdrinput.json:

     {
   "services": [
     {
       "org": "IBM",
       "url": "github.com.open-horizon.examples.sdr2msghub",
       "versionRange": "[0.0.0,INFINITY)",
       "variables": {
         "MSGHUB_API_KEY": "$MSGHUB_API_KEY"
       }
     }
   ]
 }

  3. Set the following IBM Event Streams API key in your environment. This key is different from the IBM Event Streams API key that you previously used for creating you own private IBM Event Streams instance. This key is created for use with this example and is used for feeding the IBM software-defined radio UI.

     export MSGHUB_API_KEY='2R4iaggsRB3EUYLbCcVfTZaE0M0o67UMBlb7BWDsEnxoiX64'

  4. Register your edge node to run the IBM sdr2msghub deployment pattern by running the following command:

     hzn register -n $EXCHANGE_NODEAUTH $HZN_ORG_ID IBM/sdr2msghub -f sdrinput.json

  5. Check the example web UI to see whether your edge node is sending results. For more information, see software-defined radio example web UI Opens in a new tab.

  6. You need to use guest credentials to log in to the software-defined radio web UI and view your edge node data. Use the following credentials

    • User name: guest@ibm.com
    • Password: guest123
  7. You can check whether agreements are formed by using the hzn agreement list command.
  8. You can also check whether the Docker containers in the software-defined radio deployment pattern are started by using the docker ps command.

After agreements are formed, the process to find good speech-filled radio stations to monitor can take time. The software-defined radio service searches for FM radio stations with strong signals that also consistently have human speech instead of just music. This search process can take up to an hour.

While you are waiting, you can monitor the IBM Event Streams by running the following command.

  kafkacat -C -q -o end -f "%t/%p/%o/%k: %s\n" -b $MSGHUB_BROKER_URL -X "security.protocol=sasl_ssl" -X "sasl.mechanisms=PLAIN" -X "sasl.username=${MSGHUB_API_KEY:0:16}" -X "sasl.password=${MSGHUB_API_KEY:16}" -t sdr-audio | grep -o -E '"ts":.*}'
  "ts":1539880621,"freq":92300000,"expectedValue":0.7724159,"devID":"cgiroua@us.ibm.com/gdarling-pi-sdr-1","lat":37.2458,"lon":-121.8306,"contentType":"audio/mpeg"}
  "ts":1539880658,"freq":94500000,"expectedValue":0.9805479,"devID":"cgiroua@us.ibm.com/gdarling-pi-sdr-1","lat":37.2458,"lon":-121.8306,"contentType":"audio/mpeg"}
  "ts":1539880734,"freq":100300000,"expectedValue":0.7556906,"devID":"cgiroua@us.ibm.com/gdarling-pi-sdr-1","lat":37.2458,"lon":-121.8306,"contentType":"audio/mpeg"}
  "ts":1539880769,"freq":100300000,"expectedValue":0.9982167,"devID":"cgiroua@us.ibm.com/gdarling-pi-sdr-1","lat":37.2458,"lon":-121.8306,"contentType":"audio/mpeg"}
  "ts":1539880805,"freq":94500000,"expectedValue":0.6735928,"devID":"cgiroua@us.ibm.com/gdarling-pi-sdr-1","lat":37.2458,"lon":-121.8306,"contentType":"audio/mpeg"}
  "ts":1539881275,"freq":92300000,"expectedValue":0.9998273,"devID":"cgiroua@us.ibm.com/gdarling-pi-sdr-1","lat":37.2458,"lon":-121.8306,"contentType":"audio/mpeg"}
  ...

Each message shows data from just one specific edge node, the node whose HZN_DEVICE_ID is shown in the devID field.

Note: Include the grep command at the end of the string or your console can be filled with audio data that is encoded as text.

When the service finds a radio station, you can see messages that resemble the preceding output.

If the software-defined radio service is unable to find and engage with appropriate software-defined radio hardware, the service emits a message similar to the following message into the syslog:

  Oct 18 14:17:52 raspberrypi workload-github.com-open-horizon-examples-wiki-service-sdr_0.0.1_831591dd-4505-47a4-9d51-74c0cd091f7a_sdr[358]: using mock audio

You can search the log for the preceding message with the following command:

  grep 'mock audio' /var/log/syslog

The software-defined radio example source code includes the code for the edge nodes and the code for the cloud side (including Watson Analytics and the web UI). If you are interested in developing a full-featured application for IBM Edge Computing for Devices, review this code. For more information, see Software-defined radio example code.