Radio: Accessing the Radio

This tutorial demonstrates how you can access and tune a radio.

Warm-up

Become familiar with the Radio API basics by learning about:

Initializing the Radio
Initialize the radio for use.
Scanning for All Available Radio Frequencies
Scan for radio frequencies.
Tuning the Radio and Beginning Listening
Tune in to a station and begin listening.
Seeking for a Nearby Channel
Look for radio channels nearby.

Initializing the Radio

To initialize the radio for use:

To use the functions and data types of the Radio API (in mobile and wearable applications), include the <radio.h> header file in your application:
```
#include <radio.h>
```

Define a handle for the radio using the radio_create() function:

#define MAX_FREQUENCIES 10
typedef struct radioInfo
{
   radio_h radio;
   int frequencies[MAX_FREQUENCIES];
   int num_freq;
   int selected_channel;
} mRadioInfo;

mRadioInfo mRadio;
ret = radio_create(&mRadio.radio);
if (ret != RADIO_ERROR_NONE)
{
   return false;
}

To receive notifications when your radio playback is interrupted, register the radio_set_interrupted_cb() callback function. When the application disappears into the background, use the following code:
```
ret = radio_set_interrupted_cb(mRadio.radio, on_radio_interrupted, &mRadio);
if (ret != RADIO_ERROR_NONE)
{
   // Delete the radio handle before closing the application
   return false;
}
```

Implement the callback function:

static void 
on_radio_interrupted(radio_interrupted_code_e code, void* userdata)
{
   // Search the radio handle from userdata
   mRadioInfo* mRadio = (mRadioInfo *)userdata;
 
   switch (code)
   {
   case RADIO_INTERRUPTED_COMPLETED:
      // The application, which was the source of conflict, is closed now
      // Restart the radio playback here
   break;
 
   default:
      // Your radio listening is interrupted
      // Release the application resources or save the current state here
   break;
   }
}

Scanning for All Available Radio Frequencies

To scan for available radio frequencies:

Define and set the callback for the "scan completed" notification:

ret = radio_set_scan_completed_cb(mRadio.radio, on_scan_finished, &mRadio);
if (ret != RADIO_ERROR_NONE)
{
   return false;
}

Implement the callback function:

void 
on_scan_finished(void* userdata)
{
   // Frequency scanning is done. Tune into one of the scanned frequencies
   // and start listening 
}

The callback function returns the available frequencies:

void 
on_scan_updated(int frequency, void* userdata)
{
   mRadioInfo* mRadio = (mRadioInfo *)userdata;
   // Store the radio channels in the array. Frequency values represent the kHz of the channel
   mRadio->frequencies[mRadio->num_freq++] = frequency;
}

Start scanning
```
radio_scan_start(mRadio.radio, on_scan_updated, &mRadio);
```
The scanning time depends on your environment (the strength of the radio signal). Cancel the current scan using the radio_scan_stop() function.

Tuning the Radio and Beginning Listening

To tune in to a frequency:

Select the frequency and tune into it.

ret = radio_set_frequency(mRadio.radio, mRadio.frequencies[mRadio.selected_channel]);
if (ret != RADIO_ERROR_NONE)
{
   return false;
}

Start listening to the radio using the radio_start() function:
```
ret = radio_start(mRadio.radio);
if (ret != RADIO_ERROR_NONE)
{
   return false;
}
```
If the radio emits no sound, check the signal strength with the radio_get_signal_strength() function, which returns the current signal strength as a 'dbuV' value.

Seeking for a Nearby Channel

To seek for a nearby channel:

Use the radio_seek_up() and radio_seek_down() functions to search for an active nearby channel frequency and tune into that frequency. This is very similar to the scanning operation, but only the nearest active frequency is searched for. Once the maximum frequency is reached in any direction, the search is stopped.
To seek down, use the radio_seek_down() function:
```
ret = radio_seek_down(mRadio.radio, on_seek_completed, &mRadio);
if (ret != RADIO_ERROR_NONE)
{
   return false;
} 
```
To seek down, use the radio_seek_up() function in a similar fashion.

The on_seek_completed callback returns the nearest available frequency:
```
void on_seek_completed(int frequency, void* userdata)
{
   mRadioInfo *mRadio = (mRadioInfo *)userdata;
   int new_frequency = 0;
 
   // The seek is done. The radio is tuned into the newly found frequency
   // The application sets the new frequency and updates the user interface
   radio_get_frequency(mRadio->radio, &new_frequency);	
}
```