Editing SimTX API/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">
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
</syntaxhighlight>

'''<code>monitor_ack_started</code>''' (server to client, 26 bytes):

<syntaxhighlight lang="text">
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
</syntaxhighlight>

== See also ==
* [[SimTX API/Control session#Monitoring a transmitter|Monitoring a transmitter]]

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