tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 7545

 
 
 

Protocol to Access White-Space (PAWS) Databases

Part 3 of 4, p. 34 to 66
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 34 
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]).

Top      Up      ToC       Page 35 
   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.

Top      Up      ToC       Page 36 
   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.

Top      Up      ToC       Page 37 
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.

Top      Up      ToC       Page 38 
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.

Top      Up      ToC       Page 39 
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 |
   +------------------+----------+

Top      Up      ToC       Page 40 
   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].

Top      Up      ToC       Page 41 
   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.

Top      Up      ToC       Page 42 
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 |
                                      +--------------------+----------+

Top      Up      ToC       Page 43 
   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.

Top      Up      ToC       Page 44 
   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

Top      Up      ToC       Page 45 
   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.

Top      Up      ToC       Page 46 
   +-------------------------------+
   |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.

Top      Up      ToC       Page 47 
   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}
         ],
         ...
       ]
     }
   ]

Top      Up      ToC       Page 48 
   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.

Top      Up      ToC       Page 49 
   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}
         ],
         ...
       ]
     }
   ]

Top      Up      ToC       Page 50 
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.

Top      Up      ToC       Page 51 
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.

Top      Up      ToC       Page 52 
   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.

Top      Up      ToC       Page 53 
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.

Top      Up      ToC       Page 54 
   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.

Top      Up      ToC       Page 55 
   -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 Codes

5.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.

Top      Up      ToC       Page 56 
   +---------------------------+
   |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

Top      Up      ToC       Page 57 
   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.".

Top      Up      ToC       Page 58 
   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.

Top      Up      ToC       Page 59 
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 Names

6.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.

Top      Up      ToC       Page 60 
   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.

Top      Up      ToC       Page 61 
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"
   }

Top      Up      ToC       Page 62 
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.

Top      Up      ToC       Page 63 
   {
    "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"

Top      Up      ToC       Page 64 
         },
         "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},

Top      Up      ToC       Page 65 
               {"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"
   }

Top      Up      ToC       Page 66 
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)

Next RFC Part