</p>
<p>You can change the frequency manually, using the knob or let the radio seek the station for you. The signal strength indicator can help you tune the radio.
-To obtain the list of strongest stations frequencies, press the scan buton. Scanning turns the radio off, so afterwards you have to switch it back on manually.</p>
+To obtain the list of strongest stations frequencies, press the scan buton. Scanning turns the radio off, so afterwards you have to switch it back on manually.
+Scanning also disables all the buttons. Once it is finished, buttons return to their previous states and become enabled again.</p>
<h2>Prerequisites</h2>
<p>This application requires the device to support the following feature:</p>
<span style="font-family: Courier New,Courier,monospace">__ui_cb()</span>. The first one reacts to radio module changes and sets up the
application view accordingly. The latter one does the opposite - it invokes radio module functions depending on user interface selections.</p>
+<p>There are a few types of events generated by radio controller module:</p>
+<ul>
+<li><span style="font-family: Courier New,Courier,monospace">RADIO_EVENT_SCAN_END</span> - scan command has been completed so it is necessary to unlock the UI and update the list of known frequencies,</li>
+<li><span style="font-family: Courier New,Courier,monospace">RADIO_EVENT_SCAN_UPDATE</span> - this event is generated during scan command execution, each time the device has found a station signal; this is when UI fequency display is updated,</li>
+<li><span style="font-family: Courier New,Courier,monospace">RADIO_EVENT_SEEK_END</span> - seek command has been completed and it is a good moment to update the interface's state, i.e. the frequency the device is set to,</li>
+<li><span style="font-family: Courier New,Courier,monospace">RADIO_EVENT_RSSI_UPDATE</span> - this is the event related to the radio module's internal timer; it indicates a good moment to read RSSI and update the UI accordingly,</li>
+<li><span style="font-family: Courier New,Courier,monospace">RADIO_EVENT_INTERRUPTION</span> - this event is generated when something unpredicted has occured during radio operation, like </li>
+<li><span style="font-family: Courier New,Courier,monospace">RADIO_EVENT_FREQ_SET</span> - desired frequency has been set (using frequency knob).</li>
+</ul>
+
<pre class="prettyprint">
static void __radio_cb(radio_event event)
{
}
</pre>
+<p>Events communicated from the view module to the main controller are as follows:</p>
+
+<ul>
+<li><span style="font-family: Courier New,Courier,monospace">UI_EVENT_FREQ_CHANGE</span> - this is generated multiple times as the user rotates the knob; event contains information about selected frequency; this is where the radio controller is asked to set
+it,</li>
+<li><span style="font-family: Courier New,Courier,monospace">UI_EVENT_FREQ_CHANGE_END</span> - this event occurs when the user has stopped and released the frequency knob; the UI is updated and the current frequency the device is tuned to is displayed,</li>
+<li><span style="font-family: Courier New,Courier,monospace">UI_EVENT_STATION_SELECTION</span> - generated when the user selects a frequency from the known frequencies table menu,</li>
+<li><span style="font-family: Courier New,Courier,monospace">UI_EVENT_BUTTON_ACTIVATE or UI_EVENT_BUTTON_DEACTIVATE</span> - they are generated when the user toggles one of the panel buttons on or off; radio controller function, associated with the selected button is called;
+there are five buttons in the radio panel:
+</li>
+<ul>
+<li><span style="font-family: Courier New,Courier,monospace">UI_ELEMENT_ON_OFF_BUTTON</span> - turns the radio on or off,</li>
+<li><span style="font-family: Courier New,Courier,monospace">UI_ELEMENT_MUTE_BUTTON</span> - mutes/unmutes the radio, radio mute state is preserved during scans,</li>
+<li><span style="font-family: Courier New,Courier,monospace">UI_ELEMENT_SCAN_BUTTON</span> - begins scan command and automatically shuts the radio off; this process takes some time as the whole frequency range is checked for stations,</li>
+<li><span style="font-family: Courier New,Courier,monospace">UI_ELEMENT_SEEK_MINUS_BUTTON</span> - begins seek command by gradually decreasing the frequency; seek is similar to scan, but stops on the first found station,</li>
+<li><span style="font-family: Courier New,Courier,monospace">UI_ELEMENT_SEEK_PLUS_BUTTON</span> - begins seek command by gradually increasing the frequency.</li>
+</ul>
+</ul>
+
<pre class="prettyprint">
static void __ui_cb(ui_event event, ui_element element, const void *data)
{
}
</pre>
+<p>The <span style="font-family: Courier New,Courier,monospace">__thread_function()</span> function is called in the context of another thread.
+This prevents UI lockup and allows for fluent frequency change.</p>
+
<pre class="prettyprint">
static void __thread_function(void *frequency, Ecore_Thread *thread)
{
}
</pre>
+<p>The <span style="font-family: Courier New,Courier,monospace">__thread_end_cb()</span> function is called when thread has finished. Since it is called in
+the context of the main thread, it is possible to invoke a callback function and update the UI.</p>
+
<pre class="prettyprint">
static void __thread_end_cb(void *data, Ecore_Thread *thread)
{
}
</pre>
+<p>The signal strenght is calculated in the function below. It is linearized in dBm domain. The range is from -128 to 128 dBm.</p>
+
<pre class="prettyprint">
bool radio_controller_get_rssi(float *strength)
{
}
</pre>
+<p>The function below is used to get the current radio frequency.</p>
+
<pre class="prettyprint">
bool radio_controller_get_freq(int *freq)
{
}
</pre>
+<p>The <span style="font-family: Courier New,Courier,monospace">radio_controller_get_freq_range()</span>
+function is used to get the range of frequencies the radio can operate on.
+</p>
+
<pre class="prettyprint">
bool radio_controller_get_freq_range(int *freq_min, int *freq_max)
{
projects / sdk / online-doc.git / commitdiff
