SimTX API/Packets/CoverageMapRequest

CoverageMapRequest

Frame	ClientFrame, field 35
Member	coverage_map
Direction	Client → server
Session	Control
Roles	ROLE_CONTROL.
Permission	None (a station-bound site needs an authenticated session)
Answered by	CoverageMapResponse or Error
Answers
Defined in	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 CoverageMapResponse. The official applications use it for their coverage heat maps.

Definition

message CoverageMapRequest {
  reserved 3;
  reserved "station", "adhoc";
  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;
}

Fields

#	Field	Type	Description
1	request_id	int64	Nonzero; echoed in the CoverageMapResponse or Error.
2	site	SessionSite	The hypothetical transmitter's site: a StationBinding or an AdhocStation. For an ad-hoc site the callsign is ignored. A wire_length_meters above 40 wavelengths is refused.
4	modulation	string	Modulation name.
5	frequency_hz	double	Greater than 0 and at most 3 GHz.
6	power_watts	float	Greater than 0 and at most 109 W.
7	bandwidth_hz	float	Greater than 0 and at most 2,400,000 Hz.
8	width	int32	Raster columns, 4 to 72. Clients that also talk to older servers keep to 54.
9	height	int32	Raster rows, 2 to 36. Clients that also talk to older servers keep to 27.

Reserved, never reused: field number 3 and the names station, adhoc.

Behaviour

• site is a StationBinding or an 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 Error UNAVAILABLE (Coverage prediction server is busy).
• A new request on the same session supersedes the previous one, which is answered with Error CANCELLED. Match responses by request_id.
• Servers enable coverage maps by default. A server with them switched off answers Error UNAVAILABLE (Server propagation heatmaps are disabled).
• Heavy request. Invalid values are refused with Error INVALID_REQUEST.

Examples

Complete frames, including the varint length prefix, from the protocol's golden test vectors (protocol/simtx/v25/testdata/frames.json).

coverage_map_request_adhoc (client to server, 97 bytes):

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

error_coverage_cancelled (server to client, 49 bytes):

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

See also

• CoverageMapResponse