Editing SimTX API/Packets/CoverageMapRequest

{{SimTX API navigation}}
{{SimTX packet
| name = CoverageMapRequest
| frame = ClientFrame
| field = 35
| member = coverage_map
| direction = c2s
| session = [[SimTX API/Control session|Control]]
| roles = <code>ROLE_CONTROL</code>.
| permission = None (a station-bound site needs an authenticated session)
| reply = [[SimTX API/Packets/CoverageMapResponse|CoverageMapResponse]] or [[SimTX API/Packets/Error|Error]]
| group = control
| file = control.proto
}}
'''CoverageMapRequest''' asks the server to predict where a hypothetical transmitter could be heard. The server computes the received power on a global grid and returns it in a [[SimTX API/Packets/CoverageMapResponse|CoverageMapResponse]]. The official applications use it for their coverage heat maps.

== Definition ==
<syntaxhighlight lang="protobuf">
message CoverageMapRequest {
  reserved 3;
  int64 request_id = 1;
  SessionSite site = 2;        // ad-hoc: the callsign is ignored
  string modulation = 4;       // string enum (common.proto)
  double frequency_hz = 5;
  float power_watts = 6;
  float bandwidth_hz = 7;
  int32 width = 8;
  int32 height = 9;
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>request_id</code> || <code>int64</code> || Nonzero; echoed in the [[SimTX API/Packets/CoverageMapResponse|CoverageMapResponse]] or [[SimTX API/Packets/Error|Error]].
|-
| 2 || <code>site</code> || [[SimTX API/Data types#SessionSite|SessionSite]] || The hypothetical transmitter's site: a [[SimTX API/Data types#StationBinding|StationBinding]] or an [[SimTX API/Data types#AdhocStation|AdhocStation]]. For an ad-hoc site the callsign is ignored. A <code>wire_length_meters</code> above 40 wavelengths is refused.
|-
| 4 || <code>modulation</code> || <code>string</code> || [[SimTX API/Data types#Modulation|Modulation]] name.
|-
| 5 || <code>frequency_hz</code> || <code>double</code> || Greater than 0 and at most 3 GHz.
|-
| 6 || <code>power_watts</code> || <code>float</code> || Greater than 0 and at most 10<sup>9</sup> W.
|-
| 7 || <code>bandwidth_hz</code> || <code>float</code> || Greater than 0 and at most 2,400,000 Hz.
|-
| 8 || <code>width</code> || <code>int32</code> || Raster columns, 4 to 72.
|-
| 9 || <code>height</code> || <code>int32</code> || Raster rows, 2 to 36.
|}

Field number 3 is reserved; do not use it.

== Behaviour ==
* <code>site</code> is a [[SimTX API/Data types#StationBinding|StationBinding]] or an [[SimTX API/Data types#AdhocStation|AdhocStation]], as in the session starts.
* Predictions are expensive. One runs per server at a time with one more waiting; a request beyond that is answered with [[SimTX API/Packets/Error|Error]] <code>UNAVAILABLE</code> (<i>Coverage prediction server is busy</i>).
* A new request on the same session supersedes the previous one, which is answered with [[SimTX API/Packets/Error|Error]] <code>CANCELLED</code>. Match responses by <code>request_id</code>.
* Servers enable coverage maps by default. A server with them switched off answers [[SimTX API/Packets/Error|Error]] <code>UNAVAILABLE</code> (<i>Server propagation heatmaps are disabled</i>).
* Heavy request. Invalid values are refused with [[SimTX API/Packets/Error|Error]] <code>INVALID_REQUEST</code>.

== Examples ==
Complete frames, including the varint length prefix.

'''<code>coverage_map_request_adhoc</code>''' (client to server, 97 bytes):

<syntaxhighlight lang="text">
60                                  frame length 96
9A 02 5D                            coverage_map (CoverageMapRequest), 93 bytes
  08 2A                             request_id = 42
  12 3D                             site (SessionSite), 61 bytes
    12 3B                           adhoc (AdhocStation), 59 bytes
      12 1B                         location (GeoPoint), 27 bytes
        09 00 00 00 00 00 C0 47 40  latitude_deg = 47.5
        11 00 00 00 00 00 00 33 40  longitude_deg = 19.0
        19 00 00 00 00 00 00 5E 40  altitude_meters = 120.0
      1A 1C                         antenna (AntennaConfig), 28 bytes
        0A 06 44 49 50 4F 4C 45     type = "DIPOLE"
        15 00 00 20 41              height_meters = 10
        1D 00 00 34 42              azimuth_deg = 45
        25 00 00 80 3F              feedline_loss_db = 1
        2D 9A 99 21 41              wire_length_meters = 10.1
  22 03 55 53 42                    modulation = "USB"
  29 00 00 00 00 12 D8 6A 41        frequency_hz = 14074000.0
  35 00 00 C8 42                    power_watts = 100
  3D 00 C0 28 45                    bandwidth_hz = 2700
  40 36                             width = 54
  48 1B                             height = 27
</syntaxhighlight>

'''<code>error_coverage_cancelled</code>''' (server to client, 49 bytes):

<syntaxhighlight lang="text">
30                                 frame length 48
1A 2E                              error (Error), 46 bytes
  08 0B                            code = 11 (ERROR_CODE_CANCELLED)
  12 28 50 72 65 64 69 63 74 69 …  message = "Prediction superseded by a newer request"
  18 2A                            request_id = 42
</syntaxhighlight>

== See also ==
* [[SimTX API/Packets/CoverageMapResponse|CoverageMapResponse]]

{{SimTX API navbox}}
[[Category:SimTX API]]