From: Radek Kintop <r.kintop@samsung.com>
Date: Mon, 7 Dec 2015 11:01:31 +0000 (+0100)
Subject: Mobile radio sample documentation (addendum)
X-Git-Tag: tizen_3.0/TD_SYNC/20161201~288^2
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1ac3df138fbf8fe4665da3f8ed4252bb97722d88;p=sdk%2Fonline-doc.git

Mobile radio sample documentation (addendum)

Change-Id: Ifa56dfeff413b279d313b1ba1d63bd1320217bc6
Signed-off-by: Radek Kintop <r.kintop@samsung.com>
---

diff --git a/org.tizen.sampledescriptions/html/images/radio_screen_0.png b/org.tizen.sampledescriptions/html/images/radio_screen_0.png
index 46f2cf7..6d7b5bd 100644
Binary files a/org.tizen.sampledescriptions/html/images/radio_screen_0.png and b/org.tizen.sampledescriptions/html/images/radio_screen_0.png differ
diff --git a/org.tizen.sampledescriptions/html/images/radio_screen_1.png b/org.tizen.sampledescriptions/html/images/radio_screen_1.png
index 22053bd..222961d 100644
Binary files a/org.tizen.sampledescriptions/html/images/radio_screen_1.png and b/org.tizen.sampledescriptions/html/images/radio_screen_1.png differ
diff --git a/org.tizen.sampledescriptions/html/mobile_n/radio_sd_mn.htm b/org.tizen.sampledescriptions/html/mobile_n/radio_sd_mn.htm
index eb77652..a48bc97 100644
--- a/org.tizen.sampledescriptions/html/mobile_n/radio_sd_mn.htm
+++ b/org.tizen.sampledescriptions/html/mobile_n/radio_sd_mn.htm
@@ -36,7 +36,8 @@ It takes some time for the radio hardware to set itself up.</p>
   </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>
@@ -53,6 +54,16 @@ To obtain the list of strongest stations frequencies, press the scan buton. Scan
 <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)
 {
@@ -101,6 +112,25 @@ 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)
 {
@@ -242,6 +272,9 @@ bool radio_controller_set_frequency(int freq)
 }
 </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)
 {
@@ -249,6 +282,9 @@ 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)
 {
@@ -390,6 +426,8 @@ bool radio_controller_is_muted(bool *muted)
 }
 </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)
 {
@@ -409,6 +447,8 @@ 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)
 {
@@ -416,6 +456,10 @@ 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)
 {