.. _sec-ranging-service:

RAS/RAP For Channel Sounding 
============================

This chapter serves as a guide for understanding what the 
Ranging Service (:term:`RAS`) and Ranging Profile 
(:term:`RAP`) are, their purpose, and how they fit into 
the context of Channel Sounding (:term:`CS`). It also 
provides an overview of the architecture defined by the 
ranging service and profile. The guide will discuss the 
implementation, and usage of the RAS/RAP client and server. 

.. _sec-why-ras-client:

Why RAP/RAS
^^^^^^^^^^^

The RAP client is used to request data from the peer device 
generating CS data within a CS procedure. The peer device is
a RAP server side.

RAS standardizes the transfer of CS data. It is used in applications 
such as car access, asset tracking, geo-fencing and more. 

.. note::
    According to the Ranging Profile specification, pairing must be enabled to use RRSP and RREQ, even to discover the features. 

.. _sec-rap-client-overview: 

RAS/RAP Overview
^^^^^^^^^^^^^^^^
RAS is a standardized method to collect and exchange of ranging data.

The RAP uses a client-server model to exchange CS data between the 
two devices. It contains two roles, which are used to exchange 
ranging results. The first is the Ranging Responder (:term:`RRSP`)
and corresponds with the server side. The second role is the Ranging 
Requester (:term:`RREQ`) and corresponds with the client side.

The RREQ initiates characteristic discovery for a device with server 
capabilities, and requests data from the RRSP. It must 
be able to enable RAS characteristics host by RRSP side. 

The RRSP is the device that is the GATT Server. The RRSP hosts the 
RAS and stores ranging data for future transmission. It will send 
its capabilities to the RREQ after a request and transfer results 
according to the method they both support and choose.

.. note::
    The RRSP and RREQ roles are independent of gap roles (central/peripheral) and CS roles (initiator/reflector).


RAS/RAP Client Architecture
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The below image outlines the architecture of RAS/RAP. 

.. _fig-privacy-workflow:

.. ditaa::


    +-----------------------------------------------------------------------------------------------+
    |                                 Ranging Requester                  Ranging Responder          |
    |                            /-------------------------\        /-------------------------\     |
    |                            |  +-------------------+  |        |  +-------------------+  |     |
    |   +-----------------+      |  |                   |  |        |  |    GATT Server    |  |     |
    |   |    Distance-    |      |  |    GATT CLient    |  |        |  |  +-------------+  |  |     |
    |   |   Measurements  +<-----|->+                   |  |        |  |  |     RAS     |  |  |     |
    |   |    Application  |      |  |                   |  |        |  |  +-------------+  |  |     | 
    |   +-----------------+      |  +-------------------+  |        |  +-------------------+  |     |
    |                            |  |        ATT        |  |        |  |        ATT        |  |     |
    |                            |  +-------------------+  |        |  +-------------------+  |     |
    |                            |  |       L2CAP       |  |        |  |       L2CAP       |  |     |
    |                            |  +-------------------+  |        |  +-------------------+  |     |
    |                            |        Core Host        |        |        Core Host        |     |
    |                            \-------------------------/        \-------------------------/     |
    |                                                                                               | 
    |                            /-------------------------\        /-------------------------\     |
    |                            |  +-------------------+  |        |  +-------------------+  |     |
    |                            |  |   CS initiator /  |  |        |  |   CS Reflector /  |  |     |
    |                            |  |     Reflector     |  |        |  |     initiator     |  |     |
    |                            |  +-------------------+  |        |  +-------------------+  |     |
    |                            |     Core Controller     |        |     Core Controller     |     |
    |                            \-------------------------/        \-------------------------/     |
    |                                                                                               |
    |                               Central or Peripherial             Peripherial or Central       | 
    +-----------------------------------------------------------------------------------------------+

                                            RAP / RAS Architecture

The RAS is utilized by the device assigned to the RRSP role
, which is responsible for generating the ranging results.
The RAS supports two modes of data exchange:

- Real-time Ranging Data: Instantly transmits the collected 
  ranging data to the RREQ.
- On-Demand Ranging Data: Saves the ranging data on the RAS 
  server for later retrieval by the RREQ.

.. warning:: Real-time Ranging Data feature is not supported yet.

The RRSP dictates the data exchange mode. The RRSQ will 
enable notifications or indications which communicate the
mode of data exchange. If the RRSP enables Real-time 
Ranging Data notifications or indications, the RREQ will 
configure to receive the data segments in real time. The 
RRSP will begin to send CS procedure data to the RREQ 
immediately after the CS procedure is completed. If the 
RRSP enables On-Demand Ranging Data notifications or 
indications, then the RRSP will save the data for later 
retrieval. When the RREQ is ready to receive the ranging 
data, the RREQ will send a Get Ranging Data command to the 
RRSP. The RRSP will then begin to send the CS procedure data
to the RREQ using on demand ranging data notifications of 
indications. Additionally, if one or more segments of data 
is not received by the RREQ, the RREQ write a Request Lost 
Ranging Data command. The command will request will specify
the missing data segments and trigger the RRSP to resend the
segments. The RRSP will respond with the mode notification 
or indication, then send the lost ranging data to the RREQ. 
If the RRSP has already written over the lost data, the RRSP
will respond with a No Records Found command. The RREQ must 
send a Acknowledgement of Ranging Data command or a Retrieve
Lost Ranging Data command before the configured timeout. 
The maximum timeout is 10 seconds. 

The RAS operates in only one mode at a time, determined by 
the user configuration. Examples of both modes are provided below:


.. uml::
  :caption: RAS Real-Time Ranging Data Exchange 
  :align: center

  @startuml

  participant Client 
  participant "RAS Server"

  rnote over "RAS Server"
      CS Subevent Results Info (Ranging Counter 0 with 6 subevents)
  end note
  
  group "Real-time Ranging Data"

    "RAS Server" -> Client  : Real-time Rangign Data notification or indication (1st segment)
    "RAS Server" -> Client  : Real-time Rangign Data notification or indication (nth segment)
    "RAS Server" -> Client  : Real-time Rangign Data notification or indication (last segment)
  
  end group 

  rnote over "RAS Server"
     CS Subevent Results Info (Ranging Counter 1 with 6 subevents)
  end note

  group Real-time Ranging Data 

    "RAS Server" -> Client  : Real-time Rangign Data notification or indication (1st segment)
    "RAS Server" -> Client  : Real-time Rangign Data notification or indication (nth segment)
    "RAS Server" -> Client  : Real-time Rangign Data notification or indication (last segment)
  
  end group 

  rnote over "RAS Server"
      CS Subevent Results Info (Ranging Counter 1 with 6 subevents)
  end note

  @enduml



.. uml::
  :caption: RAS On Demand Ranging Data Exchange 
  :align: center

  @startuml

  
  participant Client 
  participant "RAS Server"

  rnote over "RAS Server"
      CS Subevent Results Info (Ranging Counter 0 with 6 subevents)
  end note

  group On-Demande Ranging Data exchange procedure

      "RAS Server" -> Client  : Ranging Data Ready indication (Ranging Counter = 0)
      Client -> "RAS Server"  : Get_Ranging Data command (Op Code: 0x00, Parameter #1: Ranging Counter = 0)

      group On-Demand Ranging Data  
          "RAS Server" -> Client  : On-Demand Ranging Data notification or indication ((1st segment) = 0)
          "RAS Server" -> Client  : On-Demand Ranging Data notification or indication (nth segment)
          "RAS Server" -> Client  : On-Demand Ranging Data notification or indication (last segment)
      end group 

      "RAS Server" -> Client  : Complete Ranging Data repsonse (Op Code: 0x00, Parameter #1: Ranging Counter = 0)
       Client -> "RAS Server"  : ACK_Ranging Data command (Op Code: 0x01, Parameter #1: Ranging Counter = 0)
      "RAS Server" -> Client  : Response Code (Op Code: 0x02, Parameter #1: 0x01 Success)
 
  end group

  rnote over "RAS Server"
      CS Subevent Results Info (Ranging Counter 1 with 5 subevents)
  end note

  @enduml




The RREQ supports an abort operation command. The abort 
operation is used for on demand ranging data indications 
or notifications. If the RREQ does not receive an on demand
ranging data indication or notification within 5 seconds of 
sending an Get Ranging Data command, then the operation will
abort. The RREQ will then write an abort command to the RRSP. 
Additionally, if the RREQ does not receive an on demand 
indication or notification 1 second after the previous 
on demand indication or notification, then the RREQ will 
send an abort command. 

RRSP Ranging Data Packet structure
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The ranging data sent by the RAS server via the RRSP role, 
is standardized. The packet begins with a `Ranging Header`. 
The `Ranging Header` contains the following fields: 

- ACL Connection Event: The ACL connection event after the 
  previous CS event is completed, which will be the transmission of CS payload. 

- Frequency Compensation: 15-bit signed integer value that 
  represents the frequency compensation in parts per million (ppm). 

- Ranging Done Status: Indicates the status of the CS procedure.

- Subevent Done Status: Indicates the status of the CS subevent. 

- Ranging Abort Reason: Communicates the CS procedure abort reason. 

- Subevent Abort Reason: Communicates the CS subevent abort reason.

- Reference Power Level: Represents the reference power level from -127 to 20 dBm. 

- Number of Steps Reported: Number of steps within the CS subevent that the RRSP is reporting. 

The `Ranging Header` is sent by the RRSP at the beginning 
of the data transmission. After, a `Subevent Header` is 
sent before each subevents worth of data is reported. The
`Subevent Header` contains the following fields: 

- Step Mode [i]: Amount of steps reported by the RRSP 
  multiplied by 8.  

- Step Data [i]: Data specific to each step. Represents
  information about the mode and role of the steps being reported. 

The structure of RRSP reporting packets is defined by RAS and is described in the image below: 

.. _rrsp_ranging_body:
.. figure:: resources/RangingBody.png
    :align: center

    Ranging Data Segment
