RFC 7545
Protocol to Access White-Space (PAWS) Databases
Pages: 90
Proposed Standard
Proposed Standard
Part 3 of 4 – Pages 34 to 66
5. Protocol Parameters
This section presents more details of the parameters that make up the PAWS request and response messages. It also includes a subsection that defines response codes.5.1. GeoLocation
GeoLocation is used to specify one of the following: o a single point with optional uncertainty o a region described by a polygon These are represented using geometric shapes defined in Section 5 of "GEOPRIV Presence Information Data Format Location Object" [RFC5491], where: o A "point" with uncertainty is represented using the Ellipse shape. o A region is represented using the Polygon shape. The coordinates are expressed using the WGS84 datum [WGS-84], and units are degrees or meters. GeoLocation MAY also include a confidence level, expressed as a percentage. The confidence and uncertainty parameters may be required by some rulesets (see also [RFC7459]).
The data model for GeoLocation is illustrated below:
+------------------------------------+
|GeoLocation |
+------------------+-----------------+
|point:Ellipse | see description |
|region:Polygon | see description |
|confidence:int | OPTIONAL |
+------------------+-----------------+
Note: Point and region are mutually exclusive. Exactly one must
be present.
+-------------------------------+
|Ellipse |
+--------------------+----------+
|center:Point | REQUIRED |--+
|semiMajorAxis:float | OPTIONAL | |
|semiMinorAxis:float | OPTIONAL | |
|orientation:float | OPTIONAL | |
+--------------------+----------+ v
+---------------------------+
|Point |
+----------------+----------+
|latitude:float | REQUIRED |
|longitude:float | REQUIRED |
+----------------+----------+
+-------------------------------+
|Polygon |
+-------------------+-----------+ 4..* +---------------------------+
|exterior:list | REQUIRED |------>|Point |
+-------------------+-----------+ +----------------+----------+
|latitude:float | REQUIRED |
|longitude:float | REQUIRED |
+----------------+----------+
Parameters:
point: If present, it specifies the GeoLocation as a point.
Paradoxically, a "point" is parameterized using an Ellipse, where
the center represents the location of the point and the distances
along the major and minor axes represent the uncertainty. The
uncertainty values may be required, depending on the ruleset.
Exactly one of "point" or "region" MUST be present.
region: If present, it specifies the GeoLocation as a region.
Exactly one of "point" or "region" MUST be present.
center: The center refers to the location of a GeoLocation point and
is represented as the center of an ellipse.
latitude, longitude: Floating-point numbers that express the
latitude and longitude in degrees using the WGS84 datum [WGS-84].
semiMajorAxis, semiMinorAxis: This OPTIONAL parameter expresses the
location uncertainty, in meters. It is parameterized using
distances along the major and minor axes of the ellipse. The
default value for each parameter is 0.
orientation: This defines the orientation of the ellipse, expressed
as the rotation, in degrees, of the semi-major axis from North
towards the East. For example, when the uncertainty is greatest
along the North-South direction, orientation is 0 degrees;
conversely, if the uncertainty is greatest along the East-West
direction, orientation is 90 degrees. When orientation is not
present, the default value is 0.
exterior: When GeoLocation describes a region, the "exterior"
parameter refers to a list of latitude and longitude points that
represents the vertices of a polygon. The first and last points
MUST be the same. Thus, a minimum of 4 points is required. The
following polygon restrictions from [RFC5491] apply:
* A connecting line SHALL NOT cross another connecting line of
the same polygon.
* The vertices MUST be defined in a counter-clockwise direction,
looking at them from above.
* The edges of a polygon are defined by the shortest path between
two points in space (not a geodesic curve). Consequently, the
length between two adjacent vertices SHOULD be restricted to a
maximum of 130 km.
* Polygon shapes SHOULD be restricted to a maximum of 15 vertices
(16 points that includes the repeated vertex).
Additionally, all vertices are assumed to be at the same altitude.
confidence: The location confidence level, as a percentage, MAY be
provided. When this parameter is not provided, the default value
is 95. Valid values range from 0 to 100, but, in practice, 100%
confidence is not achievable. The confidence value is meaningful
only when GeoLocation refers to a point with uncertainty.
5.2. DeviceDescriptor
The device descriptor contains parameters that identify the specific device, such as its manufacturer serial number, manufacturer's ID, and any other device characteristics required by ruleset. +--------------------------------+ |DeviceDescriptor | +---------------------+----------+ |serialNumber:string | OPTIONAL | |manufacturerId:string| OPTIONAL | |modelId:string | OPTIONAL | 1..* |rulesetIds:list | OPTIONAL |------>string |.....................|..........| |*other:any | OPTIONAL | +---------------------+----------+ Parameters: serialNumber: The manufacturer's device serial number is OPTIONAL, although rulesets typically require it. Its maximum length is 64 octets. manufacturerId: The manufacturer's ID is OPTIONAL but may be required by some rulesets. This represents the name of the device manufacturer, and therefore ought to be consistent across all devices from the same manufacturer and distinct from that of other manufacturers. Its maximum length is 64 octets. modelId: The device's model ID is OPTIONAL but may be required by some rulesets. Its maximum length is 64 octets. rulesetIds: The list of identifiers for rulesets supported by the device (see Ruleset ID Registry (Section 9.1)). A Database MAY require that the device provides this list before servicing the device requests. If the Database supports none of the rulesets specified in the list, the Database MAY refuse to service the device requests. See RulesetInfo (Section 5.6) for discussion on ruleset identifiers. If present, the list MUST contain at least one entry. other: Depending on the ruleset, other parameters may be required. The Database MUST ignore all parameters in the message it does not understand. See PAWS Parameters Registry (Section 9.2) for additional valid parameters and for the process for extending the message with more parameters. Additionally, see PAWS Ruleset ID Registry (Section 9.1) for the valid set of parameters for each ruleset.
5.3. AntennaCharacteristics
Antenna characteristics provide additional information, such as the antenna height, antenna type, etc. Whether antenna characteristics must be provided in a request depends on the device type and ruleset. Additionally, a parameter marked as optional may be required by some rulesets. +------------------------------------+ |AntennaCharacteristics | +-------------------------+----------+ |height:float | OPTIONAL | |heightType:enum | OPTIONAL | |heightUncertainty:float | OPTIONAL | |.........................|..........| |*characteristics: | OPTIONAL | | various | | +-------------------------+----------+ Parameters: height: The antenna height in meters. Note that the height may be negative. heightType: Valid values are: AGL - Above Ground Level (default) AMSL - Above Mean Sea Level heightUncertainty: The height uncertainty in meters. NOTE: Depending on the ruleset, additional antenna characteristics may be required, such as: o antenna direction o antenna radiation pattern o antenna gain o antenna polarization These are not defined by the base protocol but may be added to the PAWS Parameters Registry, as needed.
5.4. DeviceCapabilities
Device capabilities provide additional information that may be used by the device to provide additional information to the Database that can help it to determine available spectrum. If the Database does not support device capabilities, it MUST ignore the parameter altogether. +-------------------------------+ |DeviceCapabilities | +---------------------+---------+ |frequencyRanges:list |OPTIONAL |--+ |.....................|.........| | |*other:any |OPTIONAL | | +---------------------+---------+ | 0..* V +--------------------------------+ |FrequencyRange | +----------------------+---------+ |startHz:float |REQUIRED | |stopHz:float |REQUIRED | +----------------------+---------+ Parameters: frequencyRanges: Optional FrequencyRange (Section 5.13) list. Each FrequencyRange element contains start and stop frequencies in which the device can operate. When specified, the Database SHOULD NOT return available spectrum that falls outside these ranges. other Consult the PAWS Parameters Registry (Section 9.2) for possible additional parameters. The Database MUST ignore all parameters it does not understand.5.5. DeviceOwner
DeviceOwner contains information on device ownership that is provided as part of device registration. Some rulesets may require additional parameters. +-----------------------------+ |DeviceOwner | +------------------+----------+ |owner:vcard | REQUIRED | |operator:vcard | OPTIONAL | +------------------+----------+
Parameters:
owner: The vCard contact information for the individual or business
that owns the device is REQUIRED.
operator: The vCard contact information for the device operator is
OPTIONAL but may be required by specific rulesets.
See PAWS Ruleset ID Registry (Section 9.1) for ruleset-specific
requirements on mandatory vCard properties. Depending on the
ruleset, the Database may be required to validate the device-owner
information. In these cases, the Database MUST respond with an
INVALID_VALUE error (see "Error Codes" (Section 5.17)) if validation
fails.
All contact information MUST be expressed using the structure defined
by the "vCard Format Specification" [RFC6350], encoded in JSON
[RFC7095]. Note that the vCard specification defines maximum lengths
for each parameter.
5.6. RulesetInfo
RulesetInfo contains parameters for the ruleset of a regulatory
domain that is communicated using the Initialization (Section 4.3),
Device Registration (Section 4.4), and Available Spectrum Query
(Section 4.5) components.
+------------------------------------------+
|RulesetInfo |
+------------------------------------------+
|authority:string | REQUIRED |
|rulesetId:string | REQUIRED |
|maxLocationChange:float | see description |
|maxPollingSecs:int | see description |
|..........................................|
|*other:any | OPTIONAL |
+------------------------+-----------------+
Parameters:
authority: A string that indicates the regulatory domain to which
the ruleset applies is REQUIRED. It will normally be a 2-letter
country code defined by Country Codes - ISO 3166 [ISO3166-1].
rulesetId: The ID of a ruleset for the specified authority (see
Ruleset ID Registry (Section 9.1)). The device can use this to
determine additional device behavior required by the associated
ruleset. To define new ruleset IDs, see "Defining Ruleset
Identifiers" (Section 8.1).
maxLocationChange: The maximum location change in meters is REQUIRED
for the Initialization Response (Section 4.3.2), but OPTIONAL
otherwise. Some regulatory domains mandate that, when the device
changes location by more than this specified distance, it contact
the Database to get the available spectrum for the new location.
If this value is provided by the Database within the context of an
Available Spectrum Response (Section 4.5.2), it takes precedence
over the value within the Initialization Response (Section 4.3.2).
maxPollingSecs: The maximum duration, in seconds, between requests
for available spectrum is REQUIRED for the Initialization Response
(Section 4.3.2), but OPTIONAL otherwise. The device MUST contact
the Database to get available spectrum no less frequently than
this duration. If this value is provided within the context of an
Available Spectrum Response (Section 4.5.2), it takes precedence
over the value within the Initialization Response (Section 4.3.2).
other: Depending on the ruleset, other parameters may be required.
The device MUST ignore all parameters in the message it does not
understand. Consult the PAWS Parameters Registry (Section 9.2)
for possible additional parameters.
5.7. DbUpdateSpec
This element is provided by the Database to notify devices of an
upcoming change to the database URI.
+-------------------------------+
|DbUpdateSpec |
+---------------------+---------+ +--------------------------+
|databases:list |REQUIRED |------>|DatabaseSpec |
+---------------------+---------+ 1..* +---------------+----------+
|name:string | REQUIRED |
|uri:string | REQUIRED |
+---------------+----------+
Parameters:
databases: List of one or more DatabaseSpec (Section 5.8) entries.
A device needs to update its preconfigured entry for the
responding Database with the alternate Databases listed in the
DbUpdateSpec.
5.8. DatabaseSpec
This element contains the name and URI of a Database. +--------------------------+ |DatabaseSpec | +---------------+----------+ |name:string | REQUIRED | |uri:string | REQUIRED | +---------------+----------+ Parameters: name: The display name. Its maximum length is 64 octets. uri: The corresponding URI of the Database. Its maximum length is 1024 octets.5.9. SpectrumSpec
The SpectrumSpec element encapsulates the schedule of available spectrum for a ruleset. +---------------------------------------+ |SpectrumSpec | +----------------------------+----------+ |rulesetInfo:RulesetInfo | REQUIRED | |spectrumSchedules:list | REQUIRED |-----+ |timeRange:EventTime | OPTIONAL | | |frequencyRanges:list | OPTIONAL | | |needsSpectrumReport:boolean | OPTIONAL | | |maxTotalBwHz:float | OPTIONAL | | |maxContiguousBwHz:float | OPTIONAL | | +----------------------------+----------+ | | 1..* V +-------------------------------+ |SpectrumSchedule | +--------------------+----------+ |eventTime:EventTime | REQUIRED | |spectra:list | REQUIRED | +--------------------+----------+
Parameters: rulesetInfo: RulesetInfo (Section 5.6) is REQUIRED to identify the regulatory domain and ruleset to which the spectrum schedule applies (see Ruleset ID Registry (Section 9.1)). The device needs to use the corresponding ruleset to interpret the response. Values provided within rulesetInfo, such as maxLocationChange, take precedence over the values provided by the Initialization Procedure (Section 4.3). spectrumSchedules: The SpectrumSchedule (Section 5.10) list is REQUIRED. At least one schedule MUST be included. More than one schedule MAY be included to represent future changes to the available spectrum. How far in advance a schedule may be provided depends on the ruleset. If more than one schedule is included, the eventTime intervals MUST be disjoint and MUST be sorted in increasing time. A gap in the time schedule indicates no available spectrum during that time-interval gap. timeRange: The time range for which the specification is comprehensive is OPTIONAL. When specified, any gaps in time intervals within the spectrumSchedules element that overlap with the range specified by "timeRange" are interpreted by the device as time intervals in which there is no available spectrum. frequencyRanges: Specifying the frequency ranges for which the specification is comprehensive is OPTIONAL. It is a list of disjoint FrequencyRange (Section 5.13) entries. When specified, it typically corresponds to the frequency ranges governed by the ruleset, e.g., for TV white space, the frequency ranges can correspond to the VHF and UHF bands of the associated regulatory domain. A device can combine this information with the available- spectrum specification within the spectrumSchedules element to distinguish between "unavailable spectrum" and "spectrum for which no information has been provided". needsSpectrumReport: The Database MAY return true for this parameter if spectrumSchedules list is non-empty; otherwise, the Database MAY omit this parameter altogether, in which case, the default value is false. If this parameter is present and its value is true, the device sends a SPECTRUM_USE_NOTIFY (Section 4.5.5) message to the Database; otherwise, the device SHOULD NOT send the SPECTRUM_USE_NOTIFY message. Some rulesets mandate this value be set to true.
maxTotalBwHz: The Database MAY return a constraint on the maximum
total bandwidth (in hertz) allowed, which may or may not be
contiguous. Some rulesets mandate the Database to return this
parameter. When present in the response, the device needs to
apply this constraint to its spectrum-selection logic to ensure
total bandwidth does not exceed this value.
maxContiguousBwHz: The Database MAY return a constraint on the
maximum contiguous bandwidth (in hertz) allowed. Some rulesets
mandate the Database to return this parameter. When present in
the response, the device needs to apply this constraint to its
spectrum-selection logic to ensure no single block of spectrum has
bandwidth that exceeds this value.
5.10. SpectrumSchedule
The SpectrumSchedule element combines EventTime (Section 5.14) with
Spectrum (Section 5.11) to define a time period in which the spectrum
is valid.
+-------------------------------+
|SpectrumSchedule |
+--------------------+----------+
|eventTime:EventTime | REQUIRED | +--------------------+
|spectra:list | REQUIRED |------->|Spectrum |
+--------------------+----------+ 0..* +--------------------+
|resolutionBwHz:float|
|profiles:list |
+--------------------+
Parameters:
eventTime: The EventTime (Section 5.14) is REQUIRED to express
"when" this specification is valid.
spectra: The Spectrum (Section 5.11) list is REQUIRED to specify the
available spectrum and permissible power levels, one per
resolutionBwHz. The list MAY be empty when there is no available
spectrum.
5.11. Spectrum
Available spectrum can be characterized by an ordered list of
spectrum profiles that defines permissible power levels over a set of
frequency ranges. Each Spectrum element defines permissible power
levels as maximum power spectral densities over a specified
resolution bandwidth, "resolutionBwHz". Note that the spectrum
profiles represent the "availability mask", as defined by the governing ruleset; they are not intended to encode device-level transmission-mask requirements. NOTE: Within the contexts of the AVAIL_SPECTRUM_RESP (Section 4.5.2), AVAIL_SPECTRUM_BATCH_RESP (Section 4.5.4), and SPECTRUM_USE_NOTIFY (Section 4.5.5) messages, the power levels expressed within the Spectrum messages refer to EIRP. Future extensions of PAWS may use Spectrum in other contexts for other definitions of power levels. o To support a ruleset that defines different "wide-band" and "narrow-band" power levels, PAWS allows multiple Spectrum elements to be included in the available-spectrum response, each with a different resolution bandwidth. o When multiple Spectrum elements are included in the response, each represents a constraint that the device must satisfy (logical AND). o Each Spectrum element covers the range of frequencies governed by a ruleset, rather than splitting the frequencies across multiple Spectrum elements for the same resolution bandwidth. o Each spectrum profile represents the maximum permissible power spectral density over a contiguous range of frequencies. o When multiple spectrum profiles are included, they MUST be disjoint and MUST be ordered in non-decreasing frequency value. o Gaps in frequencies between consecutive spectrum profiles represent unavailability for those frequencies. The following figure illustrates the Spectrum element and the SpectrumProfile list.
+-------------------------------+
|Spectrum |
+---------------------+---------+
|resolutionBwHz:float |REQUIRED |
|profiles:list |REQUIRED |---+
+---------------------+---------+ | 0..*
V
+-----------------------------+
|SpectrumProfile |
+-------------------+---------+
|list |REQUIRED |
+-------------------+---------+
|
V 2..*
+--------------------------+
|SpectrumProfilePoint |
+----------------+---------+
|hz:float |REQUIRED |
|dbm:float |REQUIRED |
+----------------+---------+
Parameters:
resolutionBwHz: This parameter defines the resolution bandwidth (in
hertz) over which permissible power spectral density is defined.
For example, FCC regulation would require one spectrum
specification at a bandwidth of 6 MHz, and ETSI regulation would
require two specifications, at 0.1 MHz and 8 MHz.
profiles: A SpectrumProfile (Section 5.12) list specifies
permissible power levels over a set of frequency ranges. The list
MAY be empty if there is no available spectrum.
The following example shows permitted power spectral densities for a
single resolution bandwidth of 6 MHz (for illustrative purposes
only):
[
{
"resolutionBwHz": 6e6,
"profiles": [
[
{"hz": 5.18e8, "dbm": 30.0},
{"hz": 5.30e8, "dbm": 30.0}
],
...
]
}
]
This is interpreted as:
o Over any 6 MHz within the frequency range [518 MHz, 530 MHz),
maximum permitted power is 30.0 dBm (1000 mW)
Consider now an example with two different sets of permitted power
spectral densities for the same set of frequencies over different
resolution bandwidths (for illustrative purposes only):
[
{
"resolutionBwHz": 6e6,
"profiles": [
[
{"hz": 5.18e8, "dbm": 30.0},
{"hz": 5.30e8, "dbm": 30.0}
],
...
]
},
{
"resolutionBwHz": 1e5,
"profiles": [
[
{"hz": 5.18e8, "dbm": 27.0},
{"hz": 5.30e8, "dbm": 27.0}
],
...
]
}
]
This is interpreted as:
o Over any 6 MHz within the frequency range [518 MHz, 530 MHz),
maximum permitted power is 30.0 dBm (1000 mW), and
o Over any 100 kHz within the frequency range [518 MHz, 530 MHz),
maximum permitted power is 27.0 dBm (500 mW)
This would allow, for example, operating two 100 kHz sub-channels
within the indicated 12 MHz range at 500 mW each, totaling 1000 mW.
Of course, many combinations are possible, as long as they satisfy
both conditions.
The following example encodes multiple (two) spectrum profiles, each
having a gap from 530 MHz to 536 MHz (for illustrative purposes
only):
[
{
"resolutionBwHz": 6e6,
"profiles": [
[
{"hz": 5.18e8, "dbm": 30.0},
{"hz": 5.24e8, "dbm": 30.0},
{"hz": 5.24e8, "dbm": 36.0},
{"hz": 5.30e8, "dbm": 36.0}
],
[
{"hz": 5.36e8, "dbm": 30.0},
{"hz": 5.42e8, "dbm": 30.0}
],
...
]
},
{
"resolutionBwHz": 1e5,
"profiles": [
[
{"hz": 5.18e8, "dbm": 27.0},
{"hz": 5.24e8, "dbm": 27.0},
{"hz": 5.24e8, "dbm": 30.0},
{"hz": 5.30e8, "dbm": 30.0}
],
[
{"hz": 5.36e8, "dbm": 27.0},
{"hz": 5.42e8, "dbm": 27.0}
],
...
]
}
]
5.12. SpectrumProfile
A spectrum profile is characterized by an ordered list of (frequency, power) points that represents the shape of maximum permissible power levels over a range of frequencies as a piecewise linear curve. o It MUST contain a minimum of two entries. o The entries in the list MUST be ordered in non-decreasing frequency values. o Two consecutive points MAY have the same frequency value to represent a "step function". o Three or more points MUST NOT share the same frequency value. o The first frequency is inclusive; the last frequency is exclusive. NOTE: This encoding allows presentation of "ramps" where the slope of a line segment may be finite and non-zero. The following figure illustrates the SpectrumProfile element. +-------------------------------+ |SpectrumProfile | +---------------------+---------+ |list |REQUIRED |---+ +---------------------+---------+ | 2..* V +--------------------------+ |SpectrumProfilePoint | +----------------+---------+ |hz:float |REQUIRED | |dbm:float |REQUIRED | +----------------+---------+ Parameters of each point in the profile: hz: The frequency, in hertz, at which the power level is defined. dbm: The power level, expressed as dBm per resolution bandwidth, as defined by the resolutionBwHz element of the enclosing Spectrum (Section 5.11) element.
5.13. FrequencyRange
FrequencyRange specifies a frequency range. +--------------------------------+ |FrequencyRange | +----------------------+---------+ |startHz:float |REQUIRED | |stopHz:float |REQUIRED | +----------------------+---------+ Parameters: startHz: The inclusive start of the frequency range (in hertz) is REQUIRED. stopHz: The exclusive end of the frequency range (in hertz) is REQUIRED.5.14. EventTime
The EventTime element specifies the start and stop times of an "event". This is used to indicate the time period for which a Spectrum (Section 5.11) is valid. +---------------------------+ |EventTime | +-----------------+---------+ |startTime:string |REQUIRED | |stopTime:string |REQUIRED | +-----------------+---------+ Parameters: startTime: The inclusive start of the event is REQUIRED. stopTime: The exclusive end of the event is REQUIRED. Both times are expressed using the format, YYYY-MM-DDThh:mm:ssZ, as defined by "Date and Time on the Internet: Timestamps" [RFC3339]. The times MUST be expressed using UTC.
A device that does not have access to the current date and time MUST use the timestamp at the top level of the response message as a substitute for the current time (see "Available Spectrum Response" (Section 4.5.2) and "Available Spectrum Batch Response" (Section 4.5.4)). For example, o (startTime - timestamp) gives the duration that a device must wait before the event becomes "active". If the value is zero or negative, the event is already active. o If the event is already active, (stopTime - timestamp) is the duration that the event remains active. If the value is zero or negative, the event is no longer active and MUST be ignored.5.15. GeoSpectrumSpec
The GeoSpectrumSpec element encapsulates the available spectrum for a location. It is returned within an AVAIL_SPECTRUM_BATCH_RESP (Section 4.5.4) batch response that contains multiple GeoSpectrumSpec entries, each matching a location provided in the batch request. +----------------------------------+ |GeoSpectrumSpec | +-----------------------+----------+ |location:GeoLocation | REQUIRED | |spectrumSpecs:list | REQUIRED |-------+ +-----------------------+----------+ | | 1..* V +--------------+ | SpectrumSpec | +--------------+ Parameters: location: The GeoLocation (Section 5.1) identifies the location at which the spectrum schedule applies. spectrumSpecs: The SpectrumSpec (Section 5.9) list is REQUIRED. At least one entry MUST be included. Each entry represents schedules of available spectrum for a ruleset. More than one entry MAY be included to support multiple rulesets at a location.
5.16. DeviceValidity
The DeviceValidity element is used to indicate whether a device is valid. See Section 4.6.2. +---------------------------------------+ |DeviceValidity | +----------------------------+----------+ |deviceDesc:DeviceDescriptor | REQUIRED | |isValid:boolean | REQUIRED | |reason:string | OPTIONAL | +----------------------------+----------+ Parameters: deviceDesc: The DeviceDescriptor (Section 5.2) that was used to check for validity is REQUIRED. isValid: This is a REQUIRED boolean value that indicates whether the device is valid. reason: If the device identifier is not valid, the Database MAY include a reason. The reason MAY be in any language. Its maximum length is 128 octets.5.17. Error Element
If the Database responds to a PAWS request message with an error, it MUST include an Error element. +----------------------------------+ |Error | +----------------+-----------------+ |code:int | REQUIRED | |message:string | OPTIONAL | |data:any | see description | +----------------+-----------------+ Parameters: code: An integer code that indicates the error type is REQUIRED. Values MUST be within the range -32768 to 32767, inclusive. message: A description of the error is OPTIONAL. It MAY be in any language. Its maximum length is 128 octets.
data: The Database MAY include additional data. For some errors,
additional data may be required (see Table 1). The device MUST
ignore any data parameters it does not understand.
The following table lists predefined and reserved error codes. They
are loosely grouped into the following categories:
-100s: Indicates compatibility issues, e.g., version mismatch,
unsupported or unimplemented features.
-200s: Indicates that the device request contains an error that
needs to be modified before making another request.
-300s: Indicates authorization-related issues.
Values that are not defined explicitly in the Error Codes
Table (Table 1) below are unassigned. To define new error codes, see
PAWS Error Code Registry (Section 9.3).
Code Name Description and Additional Parameters
------ ---------------- ---------------------------------------------
0 (reserved)
-100 (reserved)
-101 VERSION The Database does not support the specified
version of the message. This error does not
use any additional data.
-102 UNSUPPORTED The Database does not support the device.
For example, it supports none of the rulesets
specified in the request or does not support
the device, based on its device type, model,
etc. This error does not use any additional
data.
-103 UNIMPLEMENTED The Database does not implement the optional
request or optional feature. This error does
not use any additional data.
-104 OUTSIDE_COVERAGE The specified geolocation is outside the
coverage area of the Database. The Database
MAY include a DbUpdateSpec (Section 5.7) to
provide a list of alternate Databases that
might be appropriate for the requested
location. See OUTSIDE_COVERAGE Error
(Section 5.17.1) for more details.
-105 DATABASE_CHANGE The Database has changed its URI. The Database MAY include a DbUpdateSpec (Section 5.7) in the error response to provide devices with one or more alternate database URIs. The device needs to update its preconfigured entry for the responding Database with the alternate Databases listed in the DbUpdateSpec. See DATABASE_CHANGE Error (Section 5.17.2) for more details. -200 (reserved) -201 MISSING A required parameter is missing. The Database MUST include a list of the required parameter names. The Database MAY include only names of parameters that are missing, but MAY include a full list. Including the full list of missing parameters may reduce the number of re-queries from the device. See MISSING Error (Section 5.17.3) for more details. -202 INVALID_VALUE A parameter value is invalid in some way. The Database SHOULD include a message indicating which parameter and why its value is invalid. This error does not use any additional data. -300 (reserved) -301 UNAUTHORIZED The device is not authorized to used the Database. Authorization may be determined by the ruleset or be dependent on prior arrangement between the device and Database. This error does not use any additional data. -302 NOT_REGISTERED Device registration required, but the device is not registered. This error does not use any additional data. -32000 (reserved) Reserved for JSON-RPC error codes. to -32768 Table 1: Error Codes5.17.1. OUTSIDE_COVERAGE Error
When the error code is OUTSIDE_COVERAGE, the Database MAY include an ErrorData element within its Error response as the "data" parameter, and, if present, the ErrorData contains a DbUpdateSpec (Section 5.7) element that provides a list of alternate Databases that might be appropriate for the requested location.
+---------------------------+
|Error |
+----------------+----------+
|code:int | REQUIRED |
|message:string | OPTIONAL | +-----------------------------+
|data:ErrorData | OPTIONAL |--->|ErrorData |
+----------------+----------+ +------------------+----------+
|spec:DbUpdateSpec | OPTIONAL |
+------------------+----------+
5.17.2. DATABASE_CHANGE Error
When the error code is DATABASE_CHANGE, the Database MAY include an
ErrorData element within its Error response as the "data" parameter,
and, if present, the ErrorData contains a DbUpdateSpec (Section 5.7)
element that provides a list of alternate Databases.
+---------------------------+
|Error |
+----------------+----------+
|code:int | REQUIRED |
|message:string | OPTIONAL | +-----------------------------+
|data:ErrorData | OPTIONAL |--->|ErrorData |
+----------------+----------+ +------------------+----------+
|spec:DbUpdateSpec | REQUIRED |
+------------------+----------+
5.17.3. MISSING Error
When the error code is MISSING, the Database MUST include an
ErrorData element within its Error response as the "data" parameter,
and the ErrorData element MUST include a list of the missing required
parameters and MAY include the list of all required parameters.
+---------------------------+
|Error |
+----------------+----------+
|code:int | REQUIRED |
|message:string | OPTIONAL | +---------------------------+
|data:ErrorData | REQUIRED |--->|ErrorData |
+----------------+----------+ +----------------+----------+ 1..*
|parameters:list | REQUIRED |--+
+----------------+----------+ |
v
string
Parameters:
parameters: List of one or more parameter names (strings). The name
of a parameter is expressed using dotted notation, when
appropriate, e.g., "deviceDesc.serialNumber".
6. Message Encoding
PAWS is encoded using JSON-RPC [JSON-RPC] (see also "The JavaScript
Object Notation (JSON) Data Interchange Format" [RFC7159]). Each
component described in Protocol Functionalities (Section 4)
corresponds to one or more JSON-RPC methods. This section discusses
how to encode the data models presented in Sections 4 and 5 into JSON
and provides some example encodings. The JSON examples may contain
ellipses (...) to represent additional properties or elements that
have been omitted in order to make the examples more concise.
6.1. JSON-RPC Binding
The JSON-RPC [JSON-RPC] protocol consists of two basic objects,
Request and Response:
o The JSON-RPC Request object encapsulates a PAWS functionality
(operation) and the request message.
o The JSON-RPC Response object encapsulates a PAWS response message
and an Error element.
The Database and device MUST support JSON-RPC 2.0 encoding, with the
restriction that the "id" parameter in the messages MUST be a string.
The device should generate the "id" uniquely enough to allow the use
of JSON-RPC batch.
The JSON-RPC Request for PAWS has the following form:
{
"jsonrpc": "2.0",
"method": "spectrum.paws.methodName",
"params": <PAWS_REQ>,
"id": "idString"
}
where "method" is the name of a PAWS functionality (operation), and
<PAWS_REQ> represents one of the PAWS request messages associated
with the method (see Sections 4.3 through 4.6). Method names are
defined with the prefix "spectrum.paws.".
The non-error JSON-RPC Response for PAWS has the following form:
{
"jsonrpc": "2.0",
"result": <PAWS_RESP>,
"id": "idString"
}
where <PAWS_RESP> represents one of the PAWS response messages
associated with the method, and "id" is copied from the request.
The error JSON-RPC Response for PAWS has the following form:
{
"jsonrpc": "2.0",
"error": {
"code": -102,
"message": "An appropriate error message.",
"data": { ... }
},
"id": "idString"
}
where the "error" object corresponds to the Error Element
(Section 5.17), and "code" is an error code described in the same
section. The Database SHOULD attempt to use the most specific
applicable PAWS error code. When an accurate one is not available,
it SHOULD fall back to standard JSON-RPC error codes as defined in
the JSON-RPC specification. For example, if the Database receives
invalid JSON from the device, it should respond with "-32700",
signifying a parse error. As a last resort, the Database MAY send a
suitable HTTP 5xx response.
6.1.1. Method Names
Table 2 defines the method name, request object, and response object for each functionality defined in Protocol Functionalities (Section 4). +-------------------------------------------------------------------+ | Method Name | | Request | | Response | +-------------------------------------------------------------------+ | spectrum.paws.init | | INIT_REQ (Section 4.3.1) | | INIT_RESP (Section 4.3.2) | | | | spectrum.paws.register | | REGISTRATION_REQ (Section 4.4.1) | | REGISTRATION_RESP (Section 4.4.2) | | | | spectrum.paws.getSpectrum | | AVAIL_SPECTRUM_REQ (Section 4.5.1) | | AVAIL_SPECTRUM_RESP (Section 4.5.2) | | | | spectrum.paws.getSpectrumBatch | | AVAIL_SPECTRUM_BATCH_REQ (Section 4.5.3) | | AVAIL_SPECTRUM_BATCH_RESP (Section 4.5.4) | | | | spectrum.paws.notifySpectrumUse | | SPECTRUM_USE_NOTIFY (Section 4.5.5) | | SPECTRUM_USE_RESP (Section 4.5.6) | | | | spectrum.paws.verifyDevice | | DEV_VALID_REQ (Section 4.6.1) | | DEV_VALID_RESP (Section 4.6.2) | +-------------------------------------------------------------------+ Table 2: Method Names6.1.2. JSON Encoding of Data Models
JSON [RFC7159] encoding of the data models described in Sections 4 and 5 is straightforward: o Each data model describes the contents of a JSON object.
o Each parameter of a data model corresponds to a member of the
corresponding JSON object:
* The parameter name of the data model is the same as the member
name of the JSON object.
* The parameter data type describes the type of the member value.
o Primitive types map to JSON type, as described in Section 4 and
repeated here:
string: A JSON string, restricted to UTF-8 encoding
int: A JSON number, without a fractional or exponent part
float: A JSON number
boolean: One of the JSON values, true or false
o The list type maps to a JSON array, except that all values in the
array are of the same type.
o When the parameter data type refers to another data model, that
data model describes a nested JSON object.
o The encoded JSON object for each of the Request and Response
message listed in the Method Names Table (Table 2) also includes
the following members:
type: The name of the message, e.g., "INIT_REQ"
version: The PAWS version, e.g., "1.0"
See the following sections for examples.
6.2. Example Encoding: spectrum.paws.init Method
An example of the "spectrum.paws.init" JSON-RPC request is shown below. { "jsonrpc": "2.0", "method": "spectrum.paws.init", "params": { "type": "INIT_REQ", "version": "1.0", "deviceDesc": { "serialNumber": "XXX", "fccId": "YYY", "rulesetIds": ["FccTvBandWhiteSpace-2010"] }, "location": { "point": { "center": {"latitude": 37.0, "longitude": -101.3} } } }, "id": "xxxxxx" } An example of the corresponding JSON-RPC response is shown below. { "jsonrpc": "2.0", "result": { "type": "INIT_RESP", "version": "1.0", "rulesetInfos": [ { "authority": "us", "rulesetId": "FccTvBandWhiteSpace-2010", "maxLocationChange": 100, "maxPollingSecs": 86400 } ] }, "id": "xxxxxx" }
6.3. Example Encoding: spectrum.paws.getSpectrum Method
An example of the "spectrum.paws.getSpectrum" JSON-RPC request is shown below: { "jsonrpc": "2.0", "method": "spectrum.paws.getSpectrum", "params": { "type": "AVAIL_SPECTRUM_REQ", "version": "1.0", "deviceDesc": { "serialNumber": "XXX", "fccId": "YYY", "rulesetIds": ["FccTvBandWhiteSpace-2010"] }, "location": { "point": { "center": {"latitude": 37.0, "longitude": -101.3} } }, "antenna": {"height": 10.2, "heightType": "AGL"} }, "id": "xxxxxx" } The following example "spectrum.paws.getSpectrum" JSON-RPC response contains: o A schedule with two time ranges o A spectrum profile for one resolution bandwidth (6 MHz) o The power levels for two frequency segments: * From 518 MHz to 542 MHz * From 620 MHz to 626 MHz o In practice, each "profiles" list contains (frequency, power) points to cover all frequencies governed by the associated ruleset. See "Spectrum" (Section 5.11) for a more detailed discussion on the representation.
{
"jsonrpc": "2.0",
"result": {
"type": "AVAIL_SPECTRUM_RESP",
"version": "1.0",
"timestamp": "2013-03-02T14:30:21Z",
"deviceDesc": {
"serialNumber": "XXX",
"fccId": "YYY",
"rulesetIds": ["FccTvBandWhiteSpace-2010"]
},
"spectrumSpecs": [
{
"rulesetInfo": {
"authority": "us",
"rulesetId": "FccTvBandWhiteSpace-2010"
},
"needsSpectrumReport": false,
"spectrumSchedules": [
{
"eventTime": {
"startTime": "2013-03-02T14:30:21Z",
"stopTime": "2013-03-02T20:00:00Z"
},
"spectra": [
{
"resolutionBwHz": 6e6,
"profiles": [
...
[
{"hz":5.18e8, "dbm":30.0},
{"hz":5.36e8, "dbm":30.0},
{"hz":5.36e8, "dbm":36.0},
{"hz":5.42e8, "dbm":36.0}
],
[
{"hz":6.20e8, "dbm":30.0},
{"hz":6.26e8, "dbm":30.0}
],
...
]
}
]
},
{
"eventTime": {
"startTime": "2013-03-02T22:00:00Z",
"stopTime": "2013-03-03T14:30:21Z"
},
"spectra": [
...
]
}
]
}
]
},
"id": "xxxxxx"
}
The following example "spectrum.paws.getSpectrum" JSON-RPC response
includes a spectrum profile that contains specifications for two
different bandwidth resolutions (6 MHz and 100 kHz):
{
"jsonrpc": "2.0",
"result": {
"type": "AVAIL_SPECTRUM_RESP",
"version": "1.0",
"timestamp": "2013-03-02T14:30:21Z",
"deviceDesc": {
"serialNumber": "XXX",
...
},
"spectrumSpecs": [
{
"rulesetInfo": {
"authority": "xx",
...
},
"needsSpectrumReport": false,
"spectrumSchedules": [
{
"eventTime": {
"startTime": "2013-03-02T14:30:21Z",
"stopTime": "2013-03-02T20:00:00Z"
},
"spectra": [
{
"resolutionBwHz": 6e6,
"profiles": [
...
[
{"hz":5.18e8, "dbm":30.0},
{"hz":5.36e8, "dbm":30.0},
{"hz":5.36e8, "dbm":36.0},
{"hz":5.42e8, "dbm":36.0}
],
[
{"hz":6.20e8, "dbm":30.0},
{"hz":6.26e8, "dbm":30.0}
],
...
]
},
{
"resolutionBwHz": 1e5,
"profiles": [
...
[
{"hz":5.18e8, "dbm":27.0},
{"hz":5.36e8, "dbm":27.0},
{"hz":5.36e8, "dbm":30.0},
{"hz":5.42e8, "dbm":30.0}
],
[
{"hz":6.20e8, "dbm":27.0},
{"hz":6.26e8, "dbm":27.0}
],
...
]
}
]
},
{
"eventTime": {
"startTime": "2013-03-02T22:00:00Z",
"stopTime": "2013-03-03T14:30:21Z"
},
"spectra": [
...
]
}
]
}
]
},
"id": "xxxxxx"
}
6.4. Example Encoding: DeviceOwner vCard
The DeviceOwner (Section 5.5) data model contains member values that are JSON encodings of vCard, as described in "jCard: The JSON format for vCard" [RFC7095]. An example fragment is provided below: { ... "deviceOwner": { "owner": [ "vcard", [ ["version", {}, "text", "4.0"], ["kind", {}, "text", "org"], ["fn", {}, "text", "Racafrax, Inc."] ] ], "operator": [ "vcard", [ ["version", {}, "text", "4.0"], ["fn", {}, "text", "John Frax"], ["adr", {}, "text", ["", "", "100 Main Street", "Summersville", "CA", "90034", "USA" ] ], ["tel", {}, "uri", "tel:+1-213-555-1212"], ["email", {}, "text", "j.frax@rackafrax.com"] ] ] } }
(page 66 continued on part 4)