SimTX API/Packets/StartMonitor: Difference between revisions

Latest revision as of 17:16, 24 October 2026

API overviewQuick startHandshakeFramingAll messagesData typesStationsAccount serviceLimits and errorsv24 reference

StartMonitor
Frame	`ClientFrame`, field 31
Member	`start_monitor`
Direction	Client → server
Session	Control, moderation
Roles	`ROLE_CONTROL` (authenticated), `ROLE_MODERATION`.
Permission	Control: the transmitter must belong to the account. Moderation: `monitor.any`.
Answered by	MonitorAck, then MonitorBlock frames, or Error
Answers
Defined in	`control.proto`

StartMonitor asks the server to stream the signal of a transmitter back to the client. The stream is the transmitter's complex baseband after the modulator and amplifier model, before the antenna and propagation.

Definition[edit | edit source]

message StartMonitor { bytes session_id = 1; int64 request_id = 2; }

Fields[edit | edit source]

#	Field	Type	Description
1	`session_id`	`bytes`	16-byte session id of the transmitter to monitor.
2	`request_id`	`int64`	Nonzero; echoed in the MonitorAck or Error.

Rules[edit | edit source]

On a control session, the transmitter must belong to the same account as the control session. An anonymous control session cannot monitor anything. Authenticated control sessions need a control ticket, which the account service issues only to credentials with catalog.publish.
On a moderation session, any transmitter may be monitored with monitor.any.
Take session_id from the transmitter's own SessionStatus, or from a LiveSession.session_id in the StationList.
Success: MonitorAck with active = true, then MonitorBlock frames. Failure: Error with NOT_FOUND (no live transmitter with that id) or FORBIDDEN (not yours).
Not a heavy request. The stream starts with the newest samples; there is no backlog.

Examples[edit | edit source]

Complete frames, including the varint length prefix.

start_monitor (client to server, 24 bytes):

17                     frame length 23
FA 01 14               start_monitor (StartMonitor), 20 bytes
  0A 10 AA AA AA AA …  session_id = aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee
  10 2C                request_id = 44

monitor_ack_started (server to client, 26 bytes):

19                     frame length 25
D2 02 16               monitor_ack (MonitorAck), 22 bytes
  08 2C                request_id = 44
  12 10 AA AA AA AA …  session_id = aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee
  18 01                active = true

See also[edit | edit source]

Monitoring a transmitter

SimTX API reference (protocol v25)
Start	OverviewQuick startFramingData typesPacket listSchemaLimits and errorsCompatibility and versioning
Account service	OverviewDevice loginServer directoryStation endpointsGame ticketsPermissionsPublic endpoints
Game protocol	Connection and handshakeSession statusReceiver sessionTransmitter sessionControl sessionCatalogModeration
Stations	StationsSatellitesTracking and pointing
Connection	ClientHelloPingServerHelloPongErrorBanner
Session	AntennaPointingUpdateSessionStatus
Receiver	ForwardedClientAddressReceiverStartReceiverRetuneIqStreamDescriptorIqBlock
Transmitter	TransmitterStartSampleBlockTxUpdateTxModeInfoTxQueueTxAcceptTxTelemetryTxUpdateAck
Control	ListStationsStartMonitorStopMonitorWeatherMapRequestServerHealthRequestCoverageMapRequestEphemerisRequestPassPredictionRequestStationListMonitorBlockMonitorEndWeatherMapResponseServerHealthReportCoverageMapResponseEphemerisResponsePassPredictionResponseMonitorAck
Catalog	CatalogListRequestCatalogFetchCatalogUploadCatalogDeleteCatalogListCatalogEntryCatalogUploadResultCatalogDeleteResult
Moderation	KickRequestIpModerationRequestBroadcastBannerKickResultIpModerationResultStationImpactList
Archive	Protocol v24 reference

@@ Line 1: / Line 1: @@
-#REDIRECT [[SimTX API v24/Packets/StartMonitor]]
+{{SimTX API navigation}}
+{{SimTX packet
+| name = StartMonitor
+| frame = ClientFrame
+| field = 31
+| member = start_monitor
+| direction = c2s
+| session = [[SimTX API/Control session|Control]], [[SimTX API/Moderation session|moderation]]
+| roles = <code>ROLE_CONTROL</code> (authenticated), <code>ROLE_MODERATION</code>.
+| permission = Control: the transmitter must belong to the account. Moderation: <code>monitor.any</code>.
+| reply = [[SimTX API/Packets/MonitorAck|MonitorAck]], then [[SimTX API/Packets/MonitorBlock|MonitorBlock]] frames, or [[SimTX API/Packets/Error|Error]]
+| group = control
+| file = control.proto
+}}
+'''StartMonitor''' asks the server to stream the signal of a transmitter back to the client. The stream is the transmitter's complex baseband after the modulator and amplifier model, before the antenna and propagation.
+== Definition ==
+<syntaxhighlight lang="protobuf">
+message StartMonitor { bytes session_id = 1; int64 request_id = 2; }
+</syntaxhighlight>
+== Fields ==
+{| class="wikitable"
+! # !! Field !! Type !! Description
+|-
+| 1 || <code>session_id</code> || <code>bytes</code> || 16-byte session id of the transmitter to monitor.
+|-
+| 2 || <code>request_id</code> || <code>int64</code> || Nonzero; echoed in the [[SimTX API/Packets/MonitorAck|MonitorAck]] or [[SimTX API/Packets/Error|Error]].
+|}
+== Rules ==
+* On a control session, the transmitter must belong to the same account as the control session. An anonymous control session cannot monitor anything. Authenticated control sessions need a <code>control</code> [[SimTX API/Game tickets|ticket]], which the account service issues only to credentials with <code>catalog.publish</code>.
+* On a [[SimTX API/Moderation session|moderation session]], any transmitter may be monitored with <code>monitor.any</code>.
+* Take <code>session_id</code> from the transmitter's own [[SimTX API/Packets/SessionStatus|SessionStatus]], or from a <code>LiveSession.session_id</code> in the [[SimTX API/Packets/StationList|StationList]].
+* Success: [[SimTX API/Packets/MonitorAck|MonitorAck]] with <code>active = true</code>, then [[SimTX API/Packets/MonitorBlock|MonitorBlock]] frames. Failure: [[SimTX API/Packets/Error|Error]] with <code>NOT_FOUND</code> (no live transmitter with that id) or <code>FORBIDDEN</code> (not yours).
+* Not a heavy request. The stream starts with the newest samples; there is no backlog.
+== Examples ==
+Complete frames, including the varint length prefix.
+'''<code>start_monitor</code>''' (client to server, 24 bytes):
+<syntaxhighlight lang="text">
+                     frame length 23
+FA 01 14               start_monitor (StartMonitor), 20 bytes
+A 10 AA AA AA AA …  session_id = aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee
+2C                request_id = 44
+</syntaxhighlight>
+'''<code>monitor_ack_started</code>''' (server to client, 26 bytes):
+<syntaxhighlight lang="text">
+                     frame length 25
+D2 02 16               monitor_ack (MonitorAck), 22 bytes
+2C                request_id = 44
+10 AA AA AA AA …  session_id = aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee
+01                active = true
+</syntaxhighlight>
+== See also ==
+* [[SimTX API/Control session#Monitoring a transmitter|Monitoring a transmitter]]
+{{SimTX API navbox}}
+[[Category:SimTX API]]