942727 - Improve WebFM API, add signal strength, modify state related attributes and event handlers.

Status: RESOLVED WONTFIX

(Firefox OS Graveyard :: Gaia::FMRadio, defect)

Description

[Pin Zhang [:pzhang] (inactive)]

+++ This bug was initially created as a clone of Bug #864327 +++

Paolo proposed more improvements more than RDS supporting for WebFM API in bug 864327, I think we can bring more discussion in a separate bug, so the RDS supporting things could move on.

Comment 1

[Pin Zhang [:pzhang] (inactive)]

Attachment: Proposal based on the discussion in bug 864327

Comment 2

[Pin Zhang [:pzhang] (inactive)]

Attachment: Simple State Diagram provided by Paolo

This is the simple state diagram provide by Paolo in bug 864327, I just re-posted it.

Comment 3

[Paolo]

(In reply to Pin Zhang [:pzhang] from comment #2)
> Created attachment 8337597 [details]
> Simple State Diagram provided by Paolo
> 
> This is the simple state diagram provide by Paolo in bug 864327, I just
> re-posted it.

Hi Pin,
great to see the new proposal! A few quick comments:
-  do you know the reason why frequency is indicated with a double representing MHz? Can we consider to indicate it as a long in kHz, as in other specifications (e.g. http://mmbtools.crc.ca/files/android/doc/ca/gc/crc/libfmrds/FMinterface.html )? Maybe the long type could avoid some trouble in comparisons due to floating point operations (e.g. 95.6 != 95.600001).
- the type of state is DOMString. What if we use a short (or long), so that we have a small range of integer values? 

Another point from bug 864327, we should explicitly address multiple clients access (notifications, data flows, ...). As Marco suggested, there are relevant use cases based upon multiple clients. Perhaps we can list some of them to clarify the best strategy.

Best regards
Paolo

Comment 4

[Pin Zhang [:pzhang] (inactive)]

(In reply to Paolo from comment #3)
> Hi Pin,
> great to see the new proposal! A few quick comments:
> -  do you know the reason why frequency is indicated with a double
> representing MHz? Can we consider to indicate it as a long in kHz, as in
> other specifications (e.g.
> http://mmbtools.crc.ca/files/android/doc/ca/gc/crc/libfmrds/FMinterface.html
> )? Maybe the long type could avoid some trouble in comparisons due to
> floating point operations (e.g. 95.6 != 95.600001).
No specific reason to make the choice of frequency in mHz instead of kHz, I think the unit for attribute |frequency| should intuitively be mHz, or we need to rename it to |frequencyInKHz| specifically.

> - the type of state is DOMString. What if we use a short (or long), so that
> we have a small range of integer values? 
String values are self-explained, otherwise we need to define more constant attributes, like: navigator.mozFMRadio.STATE_DISABLED, navigator.mozFMRadio.STATE_PLAYING, etc.

> 
> Another point from bug 864327, we should explicitly address multiple clients
> access (notifications, data flows, ...). As Marco suggested, there are
> relevant use cases based upon multiple clients. Perhaps we can list some of
> them to clarify the best strategy.
> 

Currently I have no strong opinion for that, can you comment more?

> Best regards
> Paolo

Comment 5

[Marco Chen [:mchen]]

(In reply to Pin Zhang [:pzhang] from comment #4)
> > Another point from bug 864327, we should explicitly address multiple clients
> > access (notifications, data flows, ...). As Marco suggested, there are
> > relevant use cases based upon multiple clients. Perhaps we can list some of
> > them to clarify the best strategy.
> > 
> 
> Currently I have no strong opinion for that, can you comment more?
> 

Use Case:
  1. An Navigator app is launched and receives TMC from FM RDS (Frequency X).
  2. Then user enables another FM app to listen broadcast (Frequency Y).
  3. User tries to put Navigator back to foreground but found TMC is no function now. (NG)
  4. User tries to enable TMC again.
  5. User finds that broadcast/audio from FM app is changed too.

Solution 1:
  To force only one client who powered on FMRadio can control the H/W.
  Advantage:
    We can guarantee that the client powered FMRadio H/W didn't loss it's state and expectation.
  Disadvantage:
    We added more logic into design.
  Example:
    The H/W media codec now can be accessed by first media element only.
    The Camera H/W can be accessed by first app until it released it.

Solution 2:
  we allow multiple clients to access FM H/W.
  Advantage:
    Keep it simple.
  Disadvantage:
    Any app used FM Radio need to consider the error handling about interrupting by others.

Comment 6

[Paolo]

(In reply to Pin Zhang [:pzhang] from comment #4)

> No specific reason to make the choice of frequency in mHz instead of kHz, I
> think the unit for attribute |frequency| should intuitively be mHz, or we
> need to rename it to |frequencyInKHz| specifically.

My opinion is that using long and kHz units could reduce some errors/problems in future. Floating point math is not exact, comparisons are tricky, we could avoid some work to a generation of developers ;-) Moreover, CRC API and Ericsson proposal (2010) used the integer type. My vote is for an integer type (long, perhaps).

> > - the type of state is DOMString. What if we use a short (or long), so that
> > we have a small range of integer values? 
> String values are self-explained, otherwise we need to define more constant
> attributes, like: navigator.mozFMRadio.STATE_DISABLED,
> navigator.mozFMRadio.STATE_PLAYING, etc.

OK Pin. Infact, a similar principle (states->string) was also used here https://wiki.mozilla.org/WebAPI/WebTelephony#Telephony_call_states and I suppose it's more coherent with the WebAPI conventions.

Comment 7

[Paolo]

(In reply to Marco Chen [:mchen] from comment #5)

> Use Case:
>   1. An Navigator app is launched and receives TMC from FM RDS (Frequency X).
>   2. Then user enables another FM app to listen broadcast (Frequency Y).
>   3. User tries to put Navigator back to foreground but found TMC is no
> function now. (NG)
>   4. User tries to enable TMC again.
>   5. User finds that broadcast/audio from FM app is changed too.
> 
> Solution 1:
>   To force only one client who powered on FMRadio can control the H/W.
>   Advantage:
>     We can guarantee that the client powered FMRadio H/W didn't loss it's
> state and expectation.
>   Disadvantage:
>     We added more logic into design.
>   Example:
>     The H/W media codec now can be accessed by first media element only.
>     The Camera H/W can be accessed by first app until it released it.
> 
> Solution 2:
>   we allow multiple clients to access FM H/W.
>   Advantage:
>     Keep it simple.
>   Disadvantage:
>     Any app used FM Radio need to consider the error handling about
> interrupting by others.

Hi Marco, I cannot comment the HW access part. However we should be very careful not to prevent relevant use cases, while giving users the best possible experience.

Can we agree on a list of requirements? Here is a proposal:
- apps should be able to use data from the same tuner at the same time if there's no conflict
- users should always be able to control the receiver. E.g. if they want to change station should be able to do it regardless of any other app in background. 
- users can be notified if their selection (station, or TMC) has consequences on another app (e.g. navigator with TMC)

We're also aware that the same high level user experience can be achieved with different low level HW behaviors.

Comment 8

[(no longer active)]

(In reply to Paolo from comment #7)
> Hi Marco, I cannot comment the HW access part. However we should be very
> careful not to prevent relevant use cases, while giving users the best
> possible experience.
> 
> Can we agree on a list of requirements? Here is a proposal:
> - apps should be able to use data from the same tuner at the same time if
> there's no conflict
> - users should always be able to control the receiver. E.g. if they want to
> change station should be able to do it regardless of any other app in
> background. 

I think this is a key issue.  As a user, I do not want to be unable to control the radio because I have another app in the background which is already accessing it.  Given the fact that background apps can be killed without the user knowing, that would be especially bad since the radio in the foreground app will suddenly start to respond to my commands just because the background app was killed, etc.

> - users can be notified if their selection (station, or TMC) has
> consequences on another app (e.g. navigator with TMC)

I'm not sure if I agree.  I think that responsibility should be on app authors, not on our users.  In other words, app authors should be able to deal with cases where the state of the radio is modified outside of their app.  They need to do that anyways because of things such as airplane mode.

> We're also aware that the same high level user experience can be achieved
> with different low level HW behaviors.

That is good news.

Comment 9

[(no longer active)]

Comment on attachment 8337595 [details]
Proposal based on the discussion in bug 864327

>/* This Source Code Form is subject to the terms of the Mozilla Public
> * License, v. 2.0. If a copy of the MPL was not distributed with this file,
> * You can obtain one at http://mozilla.org/MPL/2.0/. */
>
>interface FMRadio : EventTarget {
>  /* Indicates if the antenna is plugged and available. */
>  readonly attribute boolean antennaAvailable;
>
>  /**
>   * Current frequency in MHz. The value will be null if the FM radio is
>   * disabled.
>   */
>  readonly attribute double? frequency;

Do we expect people to perform math on frequency values?  If this is mostly used for displaying the current frequency in the UI, then the numeric type doesn't really matter.  Also, remember that all numbers are ultimately doubles in Javascript.  :-)

>  /* The upper bound of frequency in MHz. */
>  readonly attribute double frequencyUpperBound;
>
>  /* The lower bound of frequency in MHz. */
>  readonly attribute double frequencyLowerBound;

I understand that this is the existing bits of the API, but what would be the value of these attributes if the radio is disabled?

>  /**
>   * The difference in frequency between two "adjacent" channels, in MHz. That
>   * is, any two radio channels' frequencies differ by at least channelWidth
>   * MHz. Usually, the value is one of:
>   *  - 0.05 MHz
>   *  - 0.1  MHz
>   *  - 0.2  MHz
>   */
>  readonly attribute double channelWidth;

This kind of suggests to me that people may indeed do math on the frequnecy value. :(

>  /**
>   * Indicates the current state of the FM radio HW, it is one of:
>   *   disabled, enabling, playing, seeking, paused, tuning
>   */
>  readonly attribute DOMString state;

This should be a Web IDL enum denoting what the expected values here will be.

>  /* Signal strength in dBm */
>  readonly attribute short signalStrength;

Based on the previous discussion, I'm not sure if this is the right interface to expose.  Can somebody please clarify what the exact use case for this attribute is?  Specifically, are authors expected to use the numeric value to compare it against other values, such as ones measured from different hardware and/or in different geographical locations?  I'm thinking of an app which (for whatever reason!) uploads the value that people see when listening to radio into a global data base and tries to use the average value to determine when you have a good signal in your location, etc.  Is that a sensible use case for this attribute?

>  /* Relative signal strength in the range of [0, 100]. */
>  readonly attribute short relSignalStrength;

I need to understand the exact use case for this attribute as well.

>  /**
>   * Fired when the state of FM radio HW is changed.
>   */
>  attribute EventHandler onstatechange;
>
>  /**
>   * Fired when the antenna becomes available or unavailable, i.e., fired when
>   * the antennaAvailable attribute changes.
>   */
>  attribute EventHandler onantennaavailablechange;
>
>  /* Fired when the FM radio's frequency is changed. */
>  attribute EventHandler onfrequencychange;
>
>  /**
>   * Fired when the signal strength in dBm is changed.
>   */
>  attribute EventHandler onsignalstrengthchange;

We can debate the names of these attributes later!

>  /**
>   * Power the FM radio off. The disabled event will be fired if this request
>   * completes successfully.
>   */
>  DOMRequest disable();
>
>  /**
>   * Power the FM radio on, and tune the radio to the given frequency in MHz.
>   * This will fail if the given frequency is out of range. The enabled event
>   * and frequencychange event will be fired if this request completes
>   * successfully.
>   */
>  DOMRequest enable(double frequency);
>
>  /**
>   * Tune the FM radio to the given frequency. This will fail if the given
>   * frequency is out of range.
>   *
>   * Note that the FM radio may not tuned to the exact frequency given. To get
>   * the frequency the radio is actually tuned to, wait for the request to fire
>   * sucess (or wait for the frequencychange event to fire), and then read the
>   * frequency attribute.
>   */
>  DOMRequest setFrequency(double frequency);
>
>  /**
>   * Tell the FM radio to seek up to the next channel. If the frequency is
>   * successfully changed, the frequencychange event will be triggered.
>   *
>   * Only one seek is allowed at once: If the radio is seeking when the seekUp
>   * is called, error will be fired.
>   */
>  DOMRequest seekUp();
>
>  /**
>   * Tell the FM radio to seek down to the next channel. If the frequency is
>   * successfully changed, the frequencychange event will be triggered.
>   *
>   * Only one seek is allowed at once: If the radio is seeking when the
>   * seekDown is called, error will be fired.
>   */
>  DOMRequest seekDown();
>
>  /**
>   * Cancel the seek action. If the radio is not currently seeking up or down,
>   * error will be fired.
>   */
>  DOMRequest cancelSeek();

If making backwards incompatible changes to this API is on the table at this point, I'd like to change all of these methods to return promises.

Comment 10

[Marco Chen [:mchen]]

Hi all,

I am ok of we allow multiple apps to control FMRadio HW in the same time. This is just an policy we need to make before completing the design of Web API. Thanks for all your feedback.

Comment 11

[(no longer active)]

(In reply to comment #10)
> Hi all,
> 
> I am ok of we allow multiple apps to control FMRadio HW in the same time. This
> is just an policy we need to make before completing the design of Web API.
> Thanks for all your feedback.

Sounds good to me!

Comment 12

[David Bruant]

(In reply to :Ehsan Akhgari (needinfo? me!) from comment #9)
> >  /**
> >   * Power the FM radio off. The disabled event will be fired if this request
> >   * completes successfully.
> >   */
> >  DOMRequest disable();
> >
> >  /**
> >   * Power the FM radio on, and tune the radio to the given frequency in MHz.
> >   * This will fail if the given frequency is out of range. The enabled event
> >   * and frequencychange event will be fired if this request completes
> >   * successfully.
> >   */
> >  DOMRequest enable(double frequency);
> >
> >  /**
> >   * Tune the FM radio to the given frequency. This will fail if the given
> >   * frequency is out of range.
> >   *
> >   * Note that the FM radio may not tuned to the exact frequency given. To get
> >   * the frequency the radio is actually tuned to, wait for the request to fire
> >   * sucess (or wait for the frequencychange event to fire), and then read the
> >   * frequency attribute.
> >   */
> >  DOMRequest setFrequency(double frequency);
> >
> >  /**
> >   * Tell the FM radio to seek up to the next channel. If the frequency is
> >   * successfully changed, the frequencychange event will be triggered.
> >   *
> >   * Only one seek is allowed at once: If the radio is seeking when the seekUp
> >   * is called, error will be fired.
> >   */
> >  DOMRequest seekUp();
> >
> >  /**
> >   * Tell the FM radio to seek down to the next channel. If the frequency is
> >   * successfully changed, the frequencychange event will be triggered.
> >   *
> >   * Only one seek is allowed at once: If the radio is seeking when the
> >   * seekDown is called, error will be fired.
> >   */
> >  DOMRequest seekDown();
> >
> >  /**
> >   * Cancel the seek action. If the radio is not currently seeking up or down,
> >   * error will be fired.
> >   */
> >  DOMRequest cancelSeek();
> 
> If making backwards incompatible changes to this API is on the table at this
> point, I'd like to change all of these methods to return promises.
If breaking backward compat isn't possible, making DOMRequest inherit from Promise can be a good step forward.

Comment 13

[(no longer active)]

(In reply to comment #12)
> > If making backwards incompatible changes to this API is on the table at this
> > point, I'd like to change all of these methods to return promises.
> If breaking backward compat isn't possible, making DOMRequest inherit from
> Promise can be a good step forward.

Yeah, we've talked about that general problem before...

Comment 14

[Pin Zhang [:pzhang] (inactive)]

(In reply to :Ehsan Akhgari (needinfo? me!) from comment #9)
> Comment on attachment 8337595 [details]
> Proposal based on the discussion in bug 864327
> 
> >/* This Source Code Form is subject to the terms of the Mozilla Public
> > * License, v. 2.0. If a copy of the MPL was not distributed with this file,
> > * You can obtain one at http://mozilla.org/MPL/2.0/. */
> >
> >interface FMRadio : EventTarget {
> >  /* Indicates if the antenna is plugged and available. */
> >  readonly attribute boolean antennaAvailable;
> >
> >  /**
> >   * Current frequency in MHz. The value will be null if the FM radio is
> >   * disabled.
> >   */
> >  readonly attribute double? frequency;
> 
> Do we expect people to perform math on frequency values?  If this is mostly
> used for displaying the current frequency in the UI, then the numeric type
> doesn't really matter.  Also, remember that all numbers are ultimately
> doubles in Javascript.  :-)

Except that, what I can imagine might be calculating the animation path when the frequency is changed and something like this.

BTW, Paolo, we will do frequency rounding work when frequency is set based on the frequency range and channel width, here is more detailed comments about this:
  http://mxr.mozilla.org/mozilla-central/source/dom/fmradio/FMRadioService.cpp#312

> 
> >  /* The upper bound of frequency in MHz. */
> >  readonly attribute double frequencyUpperBound;
> >
> >  /* The lower bound of frequency in MHz. */
> >  readonly attribute double frequencyLowerBound;
> 
> I understand that this is the existing bits of the API, but what would be
> the value of these attributes if the radio is disabled?
> 

It's the same as the value when radio is enabled.

> >  /**
> >   * The difference in frequency between two "adjacent" channels, in MHz. That
> >   * is, any two radio channels' frequencies differ by at least channelWidth
> >   * MHz. Usually, the value is one of:
> >   *  - 0.05 MHz
> >   *  - 0.1  MHz
> >   *  - 0.2  MHz
> >   */
> >  readonly attribute double channelWidth;
> 
> This kind of suggests to me that people may indeed do math on the frequnecy
> value. :(

Then do you think value in kHz would be better?

> 
> >  /**
> >   * Indicates the current state of the FM radio HW, it is one of:
> >   *   disabled, enabling, playing, seeking, paused, tuning
> >   */
> >  readonly attribute DOMString state;
> 
> This should be a Web IDL enum denoting what the expected values here will be.

Agree. What do you think about Paolo's suggestion, i.e. change it to short and add some state constant?

> 
> >  /* Signal strength in dBm */
> >  readonly attribute short signalStrength;
> 
> Based on the previous discussion, I'm not sure if this is the right
> interface to expose.  Can somebody please clarify what the exact use case
> for this attribute is?  Specifically, are authors expected to use the
> numeric value to compare it against other values, such as ones measured from
> different hardware and/or in different geographical locations?  I'm thinking
> of an app which (for whatever reason!) uploads the value that people see
> when listening to radio into a global data base and tries to use the average
> value to determine when you have a good signal in your location, etc.  Is
> that a sensible use case for this attribute?
> 
> >  /* Relative signal strength in the range of [0, 100]. */
> >  readonly attribute short relSignalStrength;
> 
> I need to understand the exact use case for this attribute as well.

The two attributes is the same as what WebTelephony exposes. Some use cases I can immediately imagine includes:
  - Add an signal strength indicator on the UI just like the telephony app in Gaia.
  - Recommend some other similar stations when the signal is not so good, the recommendation strategy could be based on the database of geolocation and signal strength.

Comment 15

[(no longer active)]

(In reply to comment #14)
> (In reply to :Ehsan Akhgari (needinfo? me!) from comment #9)
> > Comment on attachment 8337595 [details]
> > Proposal based on the discussion in bug 864327
> > 
> > >/* This Source Code Form is subject to the terms of the Mozilla Public
> > > * License, v. 2.0. If a copy of the MPL was not distributed with this file,
> > > * You can obtain one at http://mozilla.org/MPL/2.0/. */
> > >
> > >interface FMRadio : EventTarget {
> > >  /* Indicates if the antenna is plugged and available. */
> > >  readonly attribute boolean antennaAvailable;
> > >
> > >  /**
> > >   * Current frequency in MHz. The value will be null if the FM radio is
> > >   * disabled.
> > >   */
> > >  readonly attribute double? frequency;
> > 
> > Do we expect people to perform math on frequency values?  If this is mostly
> > used for displaying the current frequency in the UI, then the numeric type
> > doesn't really matter.  Also, remember that all numbers are ultimately
> > doubles in Javascript.  :-)
> 
> Except that, what I can imagine might be calculating the animation path when
> the frequency is changed and something like this.

Right, but I don't think that floating point precision issues will be a problem for that.

> BTW, Paolo, we will do frequency rounding work when frequency is set based on
> the frequency range and channel width, here is more detailed comments about
> this:
>  
> http://mxr.mozilla.org/mozilla-central/source/dom/fmradio/FMRadioService.cpp#312
> 
> > 
> > >  /* The upper bound of frequency in MHz. */
> > >  readonly attribute double frequencyUpperBound;
> > >
> > >  /* The lower bound of frequency in MHz. */
> > >  readonly attribute double frequencyLowerBound;
> > 
> > I understand that this is the existing bits of the API, but what would be
> > the value of these attributes if the radio is disabled?
> > 
> 
> It's the same as the value when radio is enabled.

Hmm, so are these just constant values then?

> > >  /**
> > >   * The difference in frequency between two "adjacent" channels, in MHz. That
> > >   * is, any two radio channels' frequencies differ by at least channelWidth
> > >   * MHz. Usually, the value is one of:
> > >   *  - 0.05 MHz
> > >   *  - 0.1  MHz
> > >   *  - 0.2  MHz
> > >   */
> > >  readonly attribute double channelWidth;
> > 
> > This kind of suggests to me that people may indeed do math on the frequnecy
> > value. :(
> 
> Then do you think value in kHz would be better?

Hmm, maybe.  I'm not sure what the conventional unit for FM radio frequencies is, but I believe it's MHz (please correct me if I'm wrong.)  It would be nice if we can get some feedback from gaia developers on whether they expect this to turn out to be a problem.  Can you do that please?

> > >  /**
> > >   * Indicates the current state of the FM radio HW, it is one of:
> > >   *   disabled, enabling, playing, seeking, paused, tuning
> > >   */
> > >  readonly attribute DOMString state;
> > 
> > This should be a Web IDL enum denoting what the expected values here will be.
> 
> Agree. What do you think about Paolo's suggestion, i.e. change it to short and
> add some state constant?

That's not the canonical way of doing enumerated values on the web.  WebIDL enums are the right way to do enumerated values.

> > >  /* Signal strength in dBm */
> > >  readonly attribute short signalStrength;
> > 
> > Based on the previous discussion, I'm not sure if this is the right
> > interface to expose.  Can somebody please clarify what the exact use case
> > for this attribute is?  Specifically, are authors expected to use the
> > numeric value to compare it against other values, such as ones measured from
> > different hardware and/or in different geographical locations?  I'm thinking
> > of an app which (for whatever reason!) uploads the value that people see
> > when listening to radio into a global data base and tries to use the average
> > value to determine when you have a good signal in your location, etc.  Is
> > that a sensible use case for this attribute?
> > 
> > >  /* Relative signal strength in the range of [0, 100]. */
> > >  readonly attribute short relSignalStrength;
> > 
> > I need to understand the exact use case for this attribute as well.
> 
> The two attributes is the same as what WebTelephony exposes. Some use cases I
> can immediately imagine includes:
>   - Add an signal strength indicator on the UI just like the telephony app in
> Gaia.
>   - Recommend some other similar stations when the signal is not so good, the
> recommendation strategy could be based on the database of geolocation and
> signal strength.

OK, but how do we determine whether the signal is good?  Some of the previous discussion seems to suggest that these signal strength values may be hardware dependent, which would make it very difficult to determine whether the signal is "good" or not without knowing about the details of the hardware...

Comment 16

[Pin Zhang [:pzhang] (inactive)]

(In reply to :Ehsan Akhgari (needinfo? me!) from comment #15)
> (In reply to comment #14)
> > > Do we expect people to perform math on frequency values?  If this is mostly
> > > used for displaying the current frequency in the UI, then the numeric type
> > > doesn't really matter.  Also, remember that all numbers are ultimately
> > > doubles in Javascript.  :-)
> > 
> > Except that, what I can imagine might be calculating the animation path when
> > the frequency is changed and something like this.
> 
> Right, but I don't think that floating point precision issues will be a
> problem for that.
> 

Agree.

> > > I understand that this is the existing bits of the API, but what would be
> > > the value of these attributes if the radio is disabled?
> > > 
> > 
> > It's the same as the value when radio is enabled.
> 
> Hmm, so are these just constant values then?

The values could be changed through pref which is potentially could be changed through settings api, but we didn't expose such an UI to let user change it, so I would say yes, these are constant values right now. There are detailed discussion about these attributes in bug 779500.

> 
> > 
> > Then do you think value in kHz would be better?
> 
> Hmm, maybe.  I'm not sure what the conventional unit for FM radio
> frequencies is, but I believe it's MHz (please correct me if I'm wrong.)  It
> would be nice if we can get some feedback from gaia developers on whether
> they expect this to turn out to be a problem.  Can you do that please?
> 

I implemented the FM radio app for Gaia, :), I would say it's not a problem.

> > > This should be a Web IDL enum denoting what the expected values here will be.
> > 
> > Agree. What do you think about Paolo's suggestion, i.e. change it to short and
> > add some state constant?
> 
> That's not the canonical way of doing enumerated values on the web.  WebIDL
> enums are the right way to do enumerated values.

I see.

> 
> > 
> > The two attributes is the same as what WebTelephony exposes. Some use cases I
> > can immediately imagine includes:
> >   - Add an signal strength indicator on the UI just like the telephony app in
> > Gaia.
> >   - Recommend some other similar stations when the signal is not so good, the
> > recommendation strategy could be based on the database of geolocation and
> > signal strength.
> 
> OK, but how do we determine whether the signal is good?  Some of the
> previous discussion seems to suggest that these signal strength values may
> be hardware dependent, which would make it very difficult to determine
> whether the signal is "good" or not without knowing about the details of the
> hardware...

I think that's why we definitely need a relative signal strength, and the scale function of dBm-to-relative-range should depend on the hardware, then app developers can focus on the relative value, they can choose their own threshold for good-or-not, even multiple signal strength level, like very bad, bad, not bad, good, very good etc.

Comment 17

[Paolo]

(In reply to :Ehsan Akhgari (needinfo? me!) from comment #8)
> (In reply to Paolo from comment #7)

> > - users can be notified if their selection (station, or TMC) has
> > consequences on another app (e.g. navigator with TMC)
> 
> I'm not sure if I agree.  I think that responsibility should be on app

Ops, substitute "users" with "apps". 

(In reply to :Ehsan Akhgari (needinfo? me!) from comment #9)
> Comment on attachment 8337595 [details]
> Proposal based on the discussion in bug 864327

> This kind of suggests to me that people may indeed do math on the frequnecy
> value. :(

I think so. However, it's a trade off between the previous API and ease of reading (MHz) and ease of comparing/passing to remote services. So it's up to you. Pin also points out that rounding can be done (to convert it in kHz), OK.

> Based on the previous discussion, I'm not sure if this is the right
> interface to expose.  Can somebody please clarify what the exact use case
> for this attribute is?  Specifically, are authors expected to use the
> numeric value to compare it against other values, such as ones measured from
> different hardware and/or in different geographical locations?  I'm thinking
> of an app which (for whatever reason!) uploads the value that people see
> when listening to radio into a global data base and tries to use the average
> value to determine when you have a good signal in your location, etc.  Is
> that a sensible use case for this attribute?

I think this is a key point. In general, signalStrength can be used in the following cases:
- an app compares the signalStrength value with an acceptable one (the problem to decide this "acceptable" value is open). If signal is not acceptable for a short interval, audio can simply be muted to enhance user experience (cutting the annoying noise). If signal is not acceptable for a longer interval, a decision to switch to another type of source can be done. By the way, activating signal muting on bad field conditions could be a useful option to be added. Comments?
- an app understand if the signal quality is getting worse or not comparing values on a time interval. This can be useful to make decisions whether switching to another source (e.g. IP) or not. So e.g. a [0,100] interval is better then a [0,5]
- last one, users could be used to have a visual representation of signal quality (e.g. field strength on smartphones, reception quality on radios...)

Well, maybe the signalStregth in dBm simply cannot be accessible, because it's not generally available as a chipset output. We found for example the RSSI value (also used in the RIM API implementation, interesting reading: http://www.blackberry.com/developers/docs/7.1.0api/net/rim/device/api/amms/control/fmradio/FmTunerControl.html ). RSSI is not the field strength in dBm, it only gives an internal indication of field strength. It's is a measure, but not easily translatable to dBm.

So, another option could be to use RSSI values directly, without additional computations.

I had some feedback from RadioDNS, I'm waiting for other comments from manufacturers.

> >  /* Relative signal strength in the range of [0, 100]. */
> >  readonly attribute short relSignalStrength;
> 
> I need to understand the exact use case for this attribute as well.

Same use cases. Actually, I'd remove the dBm value (signalStrength), and I'd live an RSSI value or a relative value. Again, I'm waiting for a manufacturer feedback.

Comment 18

[(no longer active)]

OK, given comment 17, I don't think that we should expose the raw signal strength.  Paolo, Pin, can you guys please come up with an alternative proposal to represent a notion of the signal strength quality?  I'd like to let you guys have full freedom on the kind of interface you'd like to expose for that because you're much more familiar with the use cases and implementation limitations than I am.  Please feel free to reach out to me if you have any questions though.

Thanks!

Comment 19

[Attila Ladanyi]

Good chipsets delivers Signal strength, multipath and if applicable RDS BER (BitErrorRate).
All of this are important for the search function.

Comment 20

[Paolo]

(In reply to :Ehsan Akhgari (needinfo? me!) from comment #18)
> OK, given comment 17, I don't think that we should expose the raw signal
> strength.  Paolo, Pin, can you guys please come up with an alternative
> proposal to represent a notion of the signal strength quality?  I'd like to
> let you guys have full freedom on the kind of interface you'd like to expose
> for that because you're much more familiar with the use cases and
> implementation limitations than I am.  Please feel free to reach out to me
> if you have any questions though.

Unfortunately I cannot help much on that. Still waiting for a feedback. Meanwhile, Attila's proposal seems very interesting. Specially, it would be great if conceptually we could map RDS BER (or errored blocks) on subjective audio quality. If such an approximation is valid, then we have the solution.

Comment 21

[Attila Ladanyi]

Attachment: Spectrum.bmp - FM Spectrum (Europe) with signal strength and frequency,

Comment 22

[Attila Ladanyi]

Attachment: RDS_Example.pdf Commonly used RDS values ​​and typical group statistics.

Comment 23

[Attila Ladanyi]

Spectrum.bmp Shows how to find useable channels. Frequencies without PI are probably with static noise. (below 40 db)
Frequencies with PI and PS name are usually excellent.
RDS quality is also an indicator of the sound quality.

The 205 channels are quickly measured for field strength.
What remains above a level (here 50) is probably (but not sure) audible program. Useful RDS is expected here over 60 dbµV

Comment 24

[Attila Ladanyi]

Attachment: Spectrum.bmp - FM Spectrum (Europe) with signal strength and frequency

Comment 25

[Attila Ladanyi]

Attachment: Spectrum.png FM Spectrum (Europe) with signal strength and frequency

Comment 26

[(no longer active)]

I have to admit that I don't know enough about this area to be able to understand Attila's proposal.  I would appreciate if somebody can please summarize it in a way that would be understandable for somebody not familiar with the jargon in this field.

Comment 27

[Michael Wu [:mwu]]

We do not implement search/seek. It's all implemented by hardware/driver. I don't think we need to be concerned with that issue at this point.

Comment 28

[Attila Ladanyi]

(In reply to Michael Wu [:mwu] from comment #27)
> We do not implement search/seek. It's all implemented by hardware/driver. I
> don't think we need to be concerned with that issue at this point.

Correct. But the search/seek is a typical HMI command. The listener wants to see a selection.
On the driver/hardware level is this more complicated and hardware depended.

Comment 29

[Paolo]

(In reply to Attila Ladanyi from comment #28)

> Correct. But the search/seek is a typical HMI command. The listener wants to
> see a selection.
> On the driver/hardware level is this more complicated and hardware depended.

Hi Attila,
You say you have data for 5 (mobile?) chipsets. If the data are public, can you send us the links?

Moreover, for all, there are technical questions blocking the advancement of the work. Maybe someone can help.
We have agreed that obtaining coherent and useful data to measure the audio quality level is not straightforward. Perhaps the RSSI or some kind signal level indication is not enough: different chipsets have measure different values AND you can have high power and low quality audio. 
Maybe RDS data can be very useful at this point. We have a kind of digital measure of the signal quality, with an Error Rate that could be mapped to audio quality. Of course it will apply only to FM/RDS networks. Important questions at this point are:
- chipsets in mobile phones should give also the number of errors in an RDS block. Could you confirm it?
- has anybody already tried to correlate (subjective) audio signal quality to RDS errors? I know the correlation exists (you can check it with a professional receiver), however, is it a significant correlation for our measure? The problem could be if with the maximum measurable RDS error level we still have an acceptable audio quality... Comments?

Comment 30

[Attila Ladanyi]

Hi Paolo.
(In reply to Paolo from comment #29)
> Hi Attila,
> You say you have data for 5 (mobile?) chipsets. If the data are public, can
> you send us the links?

I am developing professional car radios. The tuner boards are there unfortunately very specific. I am looking for mobile phones that are programmable. Unfortunately, FM is in most cases completely neglected, and closed off for developers. Only SiLabs (RDS-Forum Member) has plenty disclosed what CRC has also used. 
http://mmbtools.crc.ca/content/view/52/33/
https://www.silabs.com/Support%20Documents/TechnicalDocs/Not-Rec-for-New-Designs-Si4708-09-B.pdf
http://www.silabs.com/products/audio/fmreceivers/Pages/si470809.aspx

I have contacted ItoM (http://www.itom.nl/index.php?page=radio), who build excellent chips (I think, best of the World), but at the moment is it nowhere installed in phones. It's hard to go through the hardware supplier.

I would be really interested on what hardware base wants Firefox-OS to work.
Many phone manufacturers goes only by price, but cheap chips are usually ****.
(We also count on tenths of cents and build a 3000 Euro car Radio. Absolutely crazy!)
These also ruin the reputation of FM.

> Moreover, for all, there are technical questions blocking the advancement of
> the work. Maybe someone can help.
> We have agreed that obtaining coherent and useful data to measure the audio
> quality level is not straightforward. Perhaps the RSSI or some kind signal
> level indication is not enough: different chipsets have measure different
> values AND you can have high power and low quality audio. 

If no alternative frequencies (AF) are processed, we should better leave that to the ears.

> Maybe RDS data can be very useful at this point. We have a kind of digital
> measure of the signal quality, with an Error Rate that could be mapped to
> audio quality. Of course it will apply only to FM/RDS networks. Important
> questions at this point are:
> - chipsets in mobile phones should give also the number of errors in an RDS
> block. Could you confirm it?

Yes and no. Modern chipsets have DSP inside. You have no information about the
internal processes. Thus, not all values ​​are conducted out that could be picked up at the tuner-pin earlier.

> - has anybody already tried to correlate (subjective) audio signal quality
> to RDS errors? I know the correlation exists (you can check it with a
> professional receiver), however, is it a significant correlation for our
> measure? The problem could be if with the maximum measurable RDS error level
> we still have an acceptable audio quality... Comments?

Of course. Test drives have shown that digital always dies first.

In America first HD falls back to analog. Then continues in FM as in Europe.
The RDS error rate increases slowly until the corrections are no longer sufficient. Some older (dedicated) RDS decoder chips have earlier supplied the BER, newer stopping often simply the data. As it begins to rustle in stereo then we fall back to mono and have still a few miles audibility.
Unfortunately, recently, all functions are automated, especially with DSP based receiver.

The RDS-Forum, and also NAB/NRSC have huge interest in RDS radios in phones. I hope we come here a lot further than the CRC. 

.

Comment 31

[Paolo]

(In reply to Attila Ladanyi from comment #30)

> > quality level is not straightforward. Perhaps the RSSI or some kind signal
> > level indication is not enough: different chipsets have measure different
> > values AND you can have high power and low quality audio. 
> 
> If no alternative frequencies (AF) are processed, we should better leave
> that to the ears.

We already have alternative signal sources. E.g. we can consider IP as a fallback source. And digital networks are also an option.

> > Maybe RDS data can be very useful at this point. We have a kind of digital
> > measure of the signal quality, with an Error Rate that could be mapped to
> > audio quality. Of course it will apply only to FM/RDS networks. Important
> > questions at this point are:
> > - chipsets in mobile phones should give also the number of errors in an RDS
> > block. Could you confirm it?
> 
> Yes and no. Modern chipsets have DSP inside. You have no information about
> the
> internal processes. Thus, not all values ​​are conducted out that could be
> picked up at the tuner-pin earlier.
> 
> > - has anybody already tried to correlate (subjective) audio signal quality
> > to RDS errors? I know the correlation exists (you can check it with a
> > professional receiver), however, is it a significant correlation for our
> > measure? The problem could be if with the maximum measurable RDS error level
> > we still have an acceptable audio quality... Comments?
> 
> Of course. Test drives have shown that digital always dies first.
> 
> In America first HD falls back to analog. Then continues in FM as in Europe.
> The RDS error rate increases slowly until the corrections are no longer
> sufficient. Some older (dedicated) RDS decoder chips have earlier supplied
> the BER, newer stopping often simply the data. As it begins to rustle in
> stereo then we fall back to mono and have still a few miles audibility.
> Unfortunately, recently, all functions are automated, especially with DSP
> based receiver.

OK. An evaluation of the signal quality can be important. RSSI can be a parameter, RDS BER another one. Unfortunately, I understand from you that RDS BER cannot be reliably correlated to audio quality. On the other hand, there are also difficulties normalizing the RSSI for different chipsets.

So, pragmatically as a last chance to define a signal strength function with *available* chipsets, I propose to simply use the (raw) RSSI output parameter. It will be left to developers and tests on the field to decide if it can be useful and in which cases (and it has been used in the past in some cases). Can we agree about this point?

Comment 32

[Pin Zhang [:pzhang] (inactive)]

(In reply to Paolo from comment #31)
> 
> OK. An evaluation of the signal quality can be important. RSSI can be a
> parameter, RDS BER another one. Unfortunately, I understand from you that
> RDS BER cannot be reliably correlated to audio quality. On the other hand,
> there are also difficulties normalizing the RSSI for different chipsets.
> 
> So, pragmatically as a last chance to define a signal strength function with
> *available* chipsets, I propose to simply use the (raw) RSSI output
> parameter. It will be left to developers and tests on the field to decide if
> it can be useful and in which cases (and it has been used in the past in
> some cases). Can we agree about this point?

As my understanding, there are different ranges of RSSI for different chipsets, then if we output the raw RSSI value, we should also expose more informations about the hardware, say the name of the chip, right? otherwise I cann't imagine how a develper could handle these raw datas.

Comment 33

[(no longer active)]

(In reply to comment #32)
> (In reply to Paolo from comment #31)
> > 
> > OK. An evaluation of the signal quality can be important. RSSI can be a
> > parameter, RDS BER another one. Unfortunately, I understand from you that
> > RDS BER cannot be reliably correlated to audio quality. On the other hand,
> > there are also difficulties normalizing the RSSI for different chipsets.
> > 
> > So, pragmatically as a last chance to define a signal strength function with
> > *available* chipsets, I propose to simply use the (raw) RSSI output
> > parameter. It will be left to developers and tests on the field to decide if
> > it can be useful and in which cases (and it has been used in the past in
> > some cases). Can we agree about this point?
> 
> As my understanding, there are different ranges of RSSI for different chipsets,
> then if we output the raw RSSI value, we should also expose more informations
> about the hardware, say the name of the chip, right? otherwise I cann't imagine
> how a develper could handle these raw datas.

I think instead we should just do the work to match the value of RSSI read from the chipset with its model and possibly driver version information etc. and expose the result as a single value that the application author can use to make signal quality judgements.

Comment 34

[Pin Zhang [:pzhang] (inactive)]

(In reply to :Ehsan Akhgari (needinfo? me!) from comment #33)
> (In reply to comment #32)
> > (In reply to Paolo from comment #31)
> > > 
> > > OK. An evaluation of the signal quality can be important. RSSI can be a
> > > parameter, RDS BER another one. Unfortunately, I understand from you that
> > > RDS BER cannot be reliably correlated to audio quality. On the other hand,
> > > there are also difficulties normalizing the RSSI for different chipsets.
> > > 
> > > So, pragmatically as a last chance to define a signal strength function with
> > > *available* chipsets, I propose to simply use the (raw) RSSI output
> > > parameter. It will be left to developers and tests on the field to decide if
> > > it can be useful and in which cases (and it has been used in the past in
> > > some cases). Can we agree about this point?
> > 
> > As my understanding, there are different ranges of RSSI for different chipsets,
> > then if we output the raw RSSI value, we should also expose more informations
> > about the hardware, say the name of the chip, right? otherwise I cann't imagine
> > how a develper could handle these raw datas.
> 
> I think instead we should just do the work to match the value of RSSI read
> from the chipset with its model and possibly driver version information etc.
> and expose the result as a single value that the application author can use
> to make signal quality judgements.

I think exposing too much hardware information will make the API too complex to use, if web app developers just want to add a simple signal strength indicator, they will have to google and read lots of specs of the different type of FM chipsets.

I checked with the signalStrength and relSignalStrength exposed by wifi network information api:
  http://mxr.mozilla.org/mozilla-central/source/dom/wifi/WifiWorker.js#1313
it seems that we just set fixed max and min value for rssi and make a simple transformation from raw rssi to a relative value:
  return Math.floor(((strength - MIN_RSSI) / (MAX_RSSI - MIN_RSSI)) * 100);

can we just follow this?

Comment 35

[(no longer active)]

(In reply to comment #34)
> (In reply to :Ehsan Akhgari (needinfo? me!) from comment #33)
> > (In reply to comment #32)
> > > (In reply to Paolo from comment #31)
> > > > 
> > > > OK. An evaluation of the signal quality can be important. RSSI can be a
> > > > parameter, RDS BER another one. Unfortunately, I understand from you that
> > > > RDS BER cannot be reliably correlated to audio quality. On the other hand,
> > > > there are also difficulties normalizing the RSSI for different chipsets.
> > > > 
> > > > So, pragmatically as a last chance to define a signal strength function with
> > > > *available* chipsets, I propose to simply use the (raw) RSSI output
> > > > parameter. It will be left to developers and tests on the field to decide if
> > > > it can be useful and in which cases (and it has been used in the past in
> > > > some cases). Can we agree about this point?
> > > 
> > > As my understanding, there are different ranges of RSSI for different chipsets,
> > > then if we output the raw RSSI value, we should also expose more informations
> > > about the hardware, say the name of the chip, right? otherwise I cann't imagine
> > > how a develper could handle these raw datas.
> > 
> > I think instead we should just do the work to match the value of RSSI read
> > from the chipset with its model and possibly driver version information etc.
> > and expose the result as a single value that the application author can use
> > to make signal quality judgements.
> 
> I think exposing too much hardware information will make the API too complex to
> use, if web app developers just want to add a simple signal strength indicator,
> they will have to google and read lots of specs of the different type of FM
> chipsets.

Please read my comment again!  I think we're suggesting the same thing.  :-)

> I checked with the signalStrength and relSignalStrength exposed by wifi network
> information api:
>   http://mxr.mozilla.org/mozilla-central/source/dom/wifi/WifiWorker.js#1313
> it seems that we just set fixed max and min value for rssi and make a simple
> transformation from raw rssi to a relative value:
>   return Math.floor(((strength - MIN_RSSI) / (MAX_RSSI - MIN_RSSI)) * 100);
> 
> can we just follow this?

I'm not really the best person to suggest what a uniform cross-hardware signal strength value should be...

Comment 36

[Paolo]

(In reply to :Ehsan Akhgari (needinfo? me!) from comment #35)

> > > I think instead we should just do the work to match the value of RSSI read
> > > from the chipset with its model and possibly driver version information etc.
> > > and expose the result as a single value that the application author can use
> > > to make signal quality judgements.
> > 
> > I think exposing too much hardware information will make the API too complex to
> > use, if web app developers just want to add a simple signal strength indicator,
> > they will have to google and read lots of specs of the different type of FM
> > chipsets.
> 
> Please read my comment again!  I think we're suggesting the same thing.  :-)

> > I checked with the signalStrength and relSignalStrength exposed by wifi network
> > information api:
> >   http://mxr.mozilla.org/mozilla-central/source/dom/wifi/WifiWorker.js#1313
> > it seems that we just set fixed max and min value for rssi and make a simple
> > transformation from raw rssi to a relative value:
> >   return Math.floor(((strength - MIN_RSSI) / (MAX_RSSI - MIN_RSSI)) * 100);
> > 
> > can we just follow this?
> 
> I'm not really the best person to suggest what a uniform cross-hardware
> signal strength value should be...

OK. Of course a single, summing up value will be easier to use. Having access to RSSI MIN/MAX is good news. However it should be taken with a grain of salt. Some thoughts:
- if chipsets are different, probably the values have different non-linearities, e.g. they saturate at different points, or they could have different sensitivity. A maximum or minimum values for a chipset could be in the valid range of another one. So, after the mapping we still have different meanings for the same [0,100] range. 
- so, if you choose a [0,100], it could be very useful to describe in the docs the mapping algorithm and the key reference values (MIN/MAX or other parameters that could depend on the single chipset). 
- that will allow interested developers to understand different smartphones different behaviours, and also to further map this specific API with other Radio APIs and libraries.

Comment 37

[Pin Zhang [:pzhang] (inactive)]

(In reply to Paolo from comment #36)
> (In reply to :Ehsan Akhgari (needinfo? me!) from comment #35)
> > > I checked with the signalStrength and relSignalStrength exposed by wifi network
> > > information api:
> > >   http://mxr.mozilla.org/mozilla-central/source/dom/wifi/WifiWorker.js#1313
> > > it seems that we just set fixed max and min value for rssi and make a simple
> > > transformation from raw rssi to a relative value:
> > >   return Math.floor(((strength - MIN_RSSI) / (MAX_RSSI - MIN_RSSI)) * 100);
> > > 
> > > can we just follow this?
> > 
> > I'm not really the best person to suggest what a uniform cross-hardware
> > signal strength value should be...
> 
> OK. Of course a single, summing up value will be easier to use. Having
> access to RSSI MIN/MAX is good news. However it should be taken with a grain
> of salt. Some thoughts:
> - if chipsets are different, probably the values have different
> non-linearities, e.g. they saturate at different points, or they could have
> different sensitivity. A maximum or minimum values for a chipset could be in
> the valid range of another one. So, after the mapping we still have
> different meanings for the same [0,100] range. 
> - so, if you choose a [0,100], it could be very useful to describe in the
> docs the mapping algorithm and the key reference values (MIN/MAX or other
> parameters that could depend on the single chipset). 
> - that will allow interested developers to understand different smartphones
> different behaviours, and also to further map this specific API with other
> Radio APIs and libraries.

Do you know what the mapping algorithms of some of the common used FM chips are? I think these informations might be helpful.

Comment 38

[Paolo]

(In reply to Pin Zhang [:pzhang] from comment #37)

> Do you know what the mapping algorithms of some of the common used FM chips
> are? I think these informations might be helpful.

It would be helpful indeed. I don't have this info and we had no feedback unfortunately (it was the reason for the suggestion to transfer complexity towards developers giving them what we have now). If I get some feedback in the next days I'll report to you.

Comment 39

[(no longer active)]

(In reply to comment #38)
> (In reply to Pin Zhang [:pzhang] from comment #37)
> 
> > Do you know what the mapping algorithms of some of the common used FM chips
> > are? I think these informations might be helpful.
> 
> It would be helpful indeed. I don't have this info and we had no feedback
> unfortunately (it was the reason for the suggestion to transfer complexity
> towards developers giving them what we have now). If I get some feedback in the
> next days I'll report to you.

How should we get this information?  It seems like if we're unable to get access to this information, the application developers would be in an even worse spot in terms of getting access to this info.

Comment 40

[Paolo]

(In reply to :Ehsan Akhgari (needinfo? me!) from comment #39)
> (In reply to comment #38)
> > (In reply to Pin Zhang [:pzhang] from comment #37)
> > 
> > > Do you know what the mapping algorithms of some of the common used FM chips
> > > are? I think these informations might be helpful.
> > 
> > It would be helpful indeed. I don't have this info and we had no feedback
> > unfortunately (it was the reason for the suggestion to transfer complexity
> > towards developers giving them what we have now). If I get some feedback in the
> > next days I'll report to you.
> 
> How should we get this information?  It seems like if we're unable to get
> access to this information, the application developers would be in an even
> worse spot in terms of getting access to this info.

I cannot help much. Probably the information is in (good) data sheets. The problem is the lack of feedback from manufacturers, and, as Attila pointed out, the lack of publicly available data sheets. 
However, my opinion is that documenting Pin's suggested algorithm (and possibly RSSI_MIN/MAX for each chipset) could help a lot.

Comment 41

[Attila Ladanyi]

Data sheets are not enough.
The smartphone manufacturers make a design for the hardware. 
Here decides how and where a chip is assembled, including hardware addresses.
Whether the chip is actually responding, is the combination of hardware and kernel.
Only if you have a data channel through the kernel to the chip, is the data sheet for the chip interesting.

This means that first must know how to communicate with the Radio-chip. Everything else is "child's play".

Comment 42

[BMO Automation]

Firefox OS is not being worked on