Documentation update: device-lowlevel-api and service-api

Documentation update: device-lowlevel-api and service-api

Change-Id: I398e2937f2626e4bf0550160cc792afb74ae1c6a

BUG=none
TEST=read documentation

Committed: http://chrome-svn/viewvc/chromeos?view=rev&revision=8a0fe64

[Sam Leffler, 2010-10-01 17:16:22]

http://codereview.chromium.org/3547005/diff/1/2
File doc/device-lowlevel-api.txt (right):

http://codereview.chromium.org/3547005/diff/1/2#newcode94
doc/device-lowlevel-api.txt:94: indication.
Actually bgscan's are meant to be visible through this property; previously
there was no way for the UI to know when we did bgscan's.

http://codereview.chromium.org/3547005/diff/1/2#newcode118
doc/device-lowlevel-api.txt:118: int32 BgscanSignalThreshold [readwrite]
intentionally blank?

Method is a string identifying the algorithm to use for doing background
scanning.  Current values are "simple" and "learn" with "simple" the default.

ShortInterval is the time in seconds between doing bgscan's when actively
looking for a better AP to roam to.

SignalThreshold is the signal in dBm for triggering roaming based on receive
signal strength.

[Eric Shienbrood, 2010-10-01 18:07:35]

http://codereview.chromium.org/3547005/diff/1/2
File doc/device-lowlevel-api.txt (right):

http://codereview.chromium.org/3547005/diff/1/2#newcode157
doc/device-lowlevel-api.txt:157: If the device type is "cellular", then this
property
gives the Electronic Serial Number of the modem.

http://codereview.chromium.org/3547005/diff/1/2#newcode161
doc/device-lowlevel-api.txt:161: If the device type is "cellular", then this
property
gives the Mobile Directory Number (i.e., phone number) of the modem.

http://codereview.chromium.org/3547005/diff/1/2#newcode165
doc/device-lowlevel-api.txt:165: If the device type is "cellular", then this
property
gives the Mobile Identification Number of the modem. The MIN is often the same
as the MDN, but may change if a user changes to to a different service provider.

http://codereview.chromium.org/3547005/diff/1/2#newcode169
doc/device-lowlevel-api.txt:169: If the device type is "cellular", then this
property
identifies the hardware model of the modem. The contents of this property are
unspecified, and are useful primarily as a diagnostic aid.

http://codereview.chromium.org/3547005/diff/1/2#newcode173
doc/device-lowlevel-api.txt:173: If the device type is "cellular", then this
property
identifies the manufacturer of the modem. The contents of this property are
unspecified, and are useful primarily as a diagnostic aid.

http://codereview.chromium.org/3547005/diff/1/2#newcode177
doc/device-lowlevel-api.txt:177: If the device type is "cellular", then this
property
gives the revision of firmware that's loaded on the modem. The contents of this
property are unspecified, and are useful primarily as a diagnostic aid.

http://codereview.chromium.org/3547005/diff/1/2#newcode181
doc/device-lowlevel-api.txt:181: If the device type is "cellular", then this
property
gives the hardware revision of the modem. The contents of this property are
unspecified, and are useful primarily as a diagnostic aid.

http://codereview.chromium.org/3547005/diff/1/2#newcode185
doc/device-lowlevel-api.txt:185: If the device type is "cellular", then this
property
gives the date and time of the last over-the-air device update that was
performed, in ISO 8601 format. If an OTA update has never occurred, this
property does not exist.

http://codereview.chromium.org/3547005/diff/1/2#newcode189
doc/device-lowlevel-api.txt:189: If the device type is "cellular", then this
property
gives the revision of the Preferred Roaming List that is loaded on the modem. It
is primarily useful as a diagnostic aid.

http://codereview.chromium.org/3547005/diff/1/3
File doc/service-api.txt (right):

http://codereview.chromium.org/3547005/diff/1/3#newcode394
doc/service-api.txt:394: gives the OLP URL.
gives the URL of an online payment portal at which a user can sign up for or
modify a mobile data plan.

[Daniel Kurtz, 2010-10-03 00:48:18]

http://codereview.chromium.org/3547005/diff/1/2
File doc/device-lowlevel-api.txt (right):

http://codereview.chromium.org/3547005/diff/1/2#newcode94
doc/device-lowlevel-api.txt:94: indication.
On 2010/10/01 17:16:23, Sam Leffler wrote:
> Actually bgscan's are meant to be visible through this property; previously
> there was no way for the UI to know when we did bgscan's.

Done.

http://codereview.chromium.org/3547005/diff/1/2#newcode118
doc/device-lowlevel-api.txt:118: int32 BgscanSignalThreshold [readwrite]
On 2010/10/01 17:16:23, Sam Leffler wrote:
> intentionally blank?
> 
> Method is a string identifying the algorithm to use for doing background
> scanning.  Current values are "simple" and "learn" with "simple" the default.
> 
> ShortInterval is the time in seconds between doing bgscan's when actively
> looking for a better AP to roam to.
> 
> SignalThreshold is the signal in dBm for triggering roaming based on receive
> signal strength.

Done.

http://codereview.chromium.org/3547005/diff/1/2#newcode157
doc/device-lowlevel-api.txt:157: If the device type is "cellular", then this
property
On 2010/10/01 18:07:35, Eric Shienbrood wrote:
> gives the Electronic Serial Number of the modem.

Done.

http://codereview.chromium.org/3547005/diff/1/2#newcode161
doc/device-lowlevel-api.txt:161: If the device type is "cellular", then this
property
On 2010/10/01 18:07:35, Eric Shienbrood wrote:
> gives the Mobile Directory Number (i.e., phone number) of the modem.

Done.

http://codereview.chromium.org/3547005/diff/1/2#newcode165
doc/device-lowlevel-api.txt:165: If the device type is "cellular", then this
property
On 2010/10/01 18:07:35, Eric Shienbrood wrote:
> gives the Mobile Identification Number of the modem. The MIN is often the same
> as the MDN, but may change if a user changes to to a different service
provider.

Done.

http://codereview.chromium.org/3547005/diff/1/2#newcode169
doc/device-lowlevel-api.txt:169: If the device type is "cellular", then this
property
On 2010/10/01 18:07:35, Eric Shienbrood wrote:
> identifies the hardware model of the modem. The contents of this property are
> unspecified, and are useful primarily as a diagnostic aid.

Done.

http://codereview.chromium.org/3547005/diff/1/2#newcode173
doc/device-lowlevel-api.txt:173: If the device type is "cellular", then this
property
On 2010/10/01 18:07:35, Eric Shienbrood wrote:
> identifies the manufacturer of the modem. The contents of this property are
> unspecified, and are useful primarily as a diagnostic aid.

Done.

http://codereview.chromium.org/3547005/diff/1/2#newcode177
doc/device-lowlevel-api.txt:177: If the device type is "cellular", then this
property
On 2010/10/01 18:07:35, Eric Shienbrood wrote:
> gives the revision of firmware that's loaded on the modem. The contents of
this
> property are unspecified, and are useful primarily as a diagnostic aid.

Done.

http://codereview.chromium.org/3547005/diff/1/2#newcode181
doc/device-lowlevel-api.txt:181: If the device type is "cellular", then this
property
On 2010/10/01 18:07:35, Eric Shienbrood wrote:
> gives the hardware revision of the modem. The contents of this property are
> unspecified, and are useful primarily as a diagnostic aid.

Done.

http://codereview.chromium.org/3547005/diff/1/2#newcode185
doc/device-lowlevel-api.txt:185: If the device type is "cellular", then this
property
On 2010/10/01 18:07:35, Eric Shienbrood wrote:
> gives the date and time of the last over-the-air device update that was
> performed, in ISO 8601 format. If an OTA update has never occurred, this
> property does not exist.

Done.

http://codereview.chromium.org/3547005/diff/1/2#newcode189
doc/device-lowlevel-api.txt:189: If the device type is "cellular", then this
property
On 2010/10/01 18:07:35, Eric Shienbrood wrote:
> gives the revision of the Preferred Roaming List that is loaded on the modem.
It
> is primarily useful as a diagnostic aid.

Done.

http://codereview.chromium.org/3547005/diff/1/3
File doc/service-api.txt (right):

http://codereview.chromium.org/3547005/diff/1/3#newcode394
doc/service-api.txt:394: gives the OLP URL.
On 2010/10/01 18:07:35, Eric Shienbrood wrote:
> gives the URL of an online payment portal at which a user can sign up for or
> modify a mobile data plan.

Done.

[Eric Shienbrood, 2010-10-03 01:41:06]

LGTM

[Sam Leffler, 2010-10-03 19:15:02]

http://codereview.chromium.org/3547005/diff/7001/8001
File doc/device-lowlevel-api.txt (right):

http://codereview.chromium.org/3547005/diff/7001/8001#newcode96
doc/device-lowlevel-api.txt:96: notifying the driver.
Where did this  last sentence come from?

http://codereview.chromium.org/3547005/diff/7001/8001#newcode99
doc/device-lowlevel-api.txt:99: a scan is in progress.
Not true; please strike this.

[Daniel Kurtz, 2010-10-03 20:17:09]

http://codereview.chromium.org/3547005/diff/7001/8001
File doc/device-lowlevel-api.txt (right):

http://codereview.chromium.org/3547005/diff/7001/8001#newcode96
doc/device-lowlevel-api.txt:96: notifying the driver.
On 2010/10/03 19:15:02, Sam Leffler wrote:
> Where did this  last sentence come from?

Originally it said:
  Indicates if a device is scanning. Not all device types might support this.
Also some hardware might execute background scanning without notifying the
driver about it. Use this property only for visual indication.

Are you disagreeing with this orignal description, or my interpretation of it?

[Sam Leffler, 2010-10-04 17:51:57]

http://codereview.chromium.org/3547005/diff/7001/8001
File doc/device-lowlevel-api.txt (right):

http://codereview.chromium.org/3547005/diff/7001/8001#newcode96
doc/device-lowlevel-api.txt:96: notifying the driver.
I don't want to support this ambiguous interpretation for the property.  I
understand some devices may not signal the driver/host when they do bgscan but
I'm not sure I want to support those devices.  I'd rather we build clients so
they assume the desired behaviour which means striking this mixed message.

[Daniel Kurtz, 2010-10-04 21:07:56]

http://codereview.chromium.org/3547005/diff/7001/8001
File doc/device-lowlevel-api.txt (right):

http://codereview.chromium.org/3547005/diff/7001/8001#newcode96
doc/device-lowlevel-api.txt:96: notifying the driver.
On 2010/10/04 17:51:58, Sam Leffler wrote:
> I don't want to support this ambiguous interpretation for the property.  I
> understand some devices may not signal the driver/host when they do bgscan but
> I'm not sure I want to support those devices.  I'd rather we build clients so
> they assume the desired behaviour which means striking this mixed message. 

Done.

http://codereview.chromium.org/3547005/diff/7001/8001#newcode99
doc/device-lowlevel-api.txt:99: a scan is in progress.
On 2010/10/03 19:15:02, Sam Leffler wrote:
> Not true; please strike this.

Done.

[Sam Leffler, 2010-10-08 16:09:05]

LGTM (sorry for the delay)