Editing SimTX API/Quick start

{{SimTX API navigation}}
This page gets a program receiving from SimTX with nothing but a standard Python 3 installation. It connects anonymously, places an ad-hoc receiver in Budapest on 7.1 MHz, and prints the power of the first ten IQ blocks. It uses only the standard library, including a small hand-written protobuf codec.

For real software, generate bindings from the [[SimTX API/Schema|.proto files]] with <code>protoc</code> instead of hand-encoding messages.

== The program ==
<syntaxhighlight lang="python" line>
import math
import socket
import ssl
import struct

HOST, PORT = "argon.simtx.net", 5556


# Protobuf encoding: just enough for the two messages this client sends.

def varint(n):
    out = bytearray()
    while True:
        low, n = n & 0x7F, n >> 7
        out.append(low | 0x80 if n else low)
        if not n:
            return bytes(out)


def f_varint(field, value):          # int32, int64, bool and enum fields
    return varint(field << 3 | 0) + varint(value)


def f_double(field, value):
    return varint(field << 3 | 1) + struct.pack("<d", value)


def f_float(field, value):
    return varint(field << 3 | 5) + struct.pack("<f", value)


def f_bytes(field, data):            # string, bytes and nested message fields
    if isinstance(data, str):
        data = data.encode("utf-8")
    return varint(field << 3 | 2) + varint(len(data)) + data


# Protobuf decoding: a message becomes {field number: last value seen}.

def read_varint(buf, i):
    value = shift = 0
    while True:
        b = buf[i]
        i += 1
        value |= (b & 0x7F) << shift
        shift += 7
        if not b & 0x80:
            return value, i


def decode(buf):
    fields, i = {}, 0
    while i < len(buf):
        key, i = read_varint(buf, i)
        field, wire_type = key >> 3, key & 7
        if wire_type == 0:
            value, i = read_varint(buf, i)
        elif wire_type == 1:
            value, i = buf[i:i + 8], i + 8
        elif wire_type == 2:
            n, i = read_varint(buf, i)
            value, i = buf[i:i + n], i + n
        elif wire_type == 5:
            value, i = buf[i:i + 4], i + 4
        else:
            raise ValueError(f"unexpected wire type {wire_type}")
        fields[field] = value
    return fields


def f64(fields, n):
    return struct.unpack("<d", fields[n])[0] if n in fields else 0.0


def f32(fields, n):
    return struct.unpack("<f", fields[n])[0] if n in fields else 0.0


def text(fields, n):
    return fields.get(n, b"").decode("utf-8", "replace")


# Framing: varint length, then one ClientFrame or ServerFrame.

def read_exact(sock, n):
    buf = bytearray()
    while len(buf) < n:
        chunk = sock.recv(n - len(buf))
        if not chunk:
            raise ConnectionError("server closed the connection")
        buf += chunk
    return bytes(buf)


def read_frame(sock):
    length = shift = 0
    while True:
        b = read_exact(sock, 1)[0]
        length |= (b & 0x7F) << shift
        shift += 7
        if not b & 0x80:
            break
    frame = decode(read_exact(sock, length))
    for member, payload in frame.items():   # a frame holds one oneof member
        return member, payload
    return 0, b""                            # empty frame: skip it


def send_frame(sock, member, message):
    frame = f_bytes(member, message)
    sock.sendall(varint(len(frame)) + frame)


raw = socket.create_connection((HOST, PORT), timeout=10)
raw.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
sock = ssl.create_default_context().wrap_socket(raw, server_hostname=HOST)

# Preface: "SIMT", protocol version 25
sock.sendall(struct.pack(">II", 0x53494D54, 25))

# hello (1): ClientHello { role: ROLE_RECEIVER, client_name, client_version }
send_frame(sock, 1, f_varint(1, 1) + f_bytes(4, "quick-start.py") + f_bytes(5, "1.0"))

member, payload = read_frame(sock)
hello = decode(payload)
if member != 1 or hello.get(1, 0) != 1:      # hello_result, HELLO_STATUS_ACCEPTED
    raise SystemExit(f"hello rejected ({hello.get(1, 0)}): {text(hello, 2)}")

# receiver_start (10): an ad-hoc receiver in Budapest with a 10 m dipole, on 7.1 MHz
location = f_double(1, 47.4979) + f_double(2, 19.0402) + f_double(3, 120.0)
antenna = f_bytes(1, "DIPOLE") + f_float(2, 10.0)
adhoc = f_bytes(1, "N0CALL") + f_bytes(2, location) + f_bytes(3, antenna)
start = (
    f_bytes(1, f_bytes(2, adhoc))            # site { adhoc { ... } }
    + f_double(3, 7_100_000.0)               # center_frequency_hz
    + f_float(4, 48_000.0)                   # bandwidth_hz
    + f_varint(5, 48_000)                    # sample_rate
    + f_varint(6, 4_800)                     # chunk_samples
)
send_frame(sock, 10, start)

chunk, int8, blocks = 0, False, 0
while blocks < 10:
    member, payload = read_frame(sock)
    message = decode(payload)
    if member == 10:                         # session_status
        state = message.get(1, 0)
        if state != 1:                       # anything but SESSION_STATE_BOUND
            raise SystemExit(f"session state {state}, code {message.get(3, 0)}: {text(message, 2)}")
        print("bound, session id", message.get(4, b"").hex())
    elif member == 11:                       # iq_descriptor
        rate, chunk, int8 = message.get(1, 0), message.get(3, 0), message.get(4, 0) == 1
        print(f"stream: {rate} S/s at {f64(message, 2):.0f} Hz, {chunk} samples/block")
    elif member == 12:                       # iq
        scale, samples = f32(message, 1), message.get(2, b"")
        count = len(samples) if int8 else len(samples) // 2
        values = struct.unpack((">%db" if int8 else ">%dh") % count, samples)
        full_scale = 127 if int8 else 32767
        power = sum((v * scale / full_scale) ** 2 for v in values) / chunk
        sequence = struct.unpack("<Q", message[5])[0] if 5 in message else 0
        print(f"block {sequence}: {-12 + 10 * math.log10(max(power, 1e-30)):.1f} dBm")
        blocks += 1
    elif member == 3:                        # error
        raise SystemExit(f"error {message.get(1, 0)}: {text(message, 2)}")
    # pong, banner and frames this client does not know: ignore

sock.close()
</syntaxhighlight>

== What it does ==
# '''Connects''' with TLS to the public server and sets <code>TCP_NODELAY</code>. Real software should take the host and port from the [[SimTX API/Server directory|server directory]] or from its configuration; they are hard-coded here for brevity.
# '''Sends the preface''', the 8 bytes <code>53 49 4D 54 00 00 00 19</code>: "SIMT" and the protocol version 25. See [[SimTX API/Framing#Preface|Preface]].
# '''Sends a [[SimTX API/Packets/ClientHello|ClientHello]]''' as <code>ClientFrame</code> member 1, with <code>role = ROLE_RECEIVER</code> (1). <code>auth</code> is left at 0, <code>AUTH_KIND_ANONYMOUS</code>, so no fields are needed for it: protobuf omits zero values.
# '''Reads the [[SimTX API/Packets/ServerHello|ServerHello]]''' (<code>ServerFrame</code> member 1) and stops unless its <code>status</code> is <code>HELLO_STATUS_ACCEPTED</code> (1).
# '''Sends a [[SimTX API/Packets/ReceiverStart|ReceiverStart]]''' (member 10) whose <code>site</code> is an [[SimTX API/Data types#AdhocStation|AdhocStation]]: callsign, position and a dipole 10 m above ground. A <code>wire_length_meters</code> of 0 sizes the dipole for the frequency.
# '''Reads frames''' in a loop and dispatches on the member number: [[SimTX API/Packets/SessionStatus|SessionStatus]] (10) must say <code>SESSION_STATE_BOUND</code>; [[SimTX API/Packets/IqStreamDescriptor|IqStreamDescriptor]] (11) gives the negotiated rate and block size; each [[SimTX API/Packets/IqBlock|IqBlock]] (12) is decoded and its power printed; an [[SimTX API/Packets/Error|Error]] (3) stops the program. Every other frame is ignored, as the protocol requires.

== Things to notice ==
* '''Two byte orders.''' Protobuf scalars such as <code>double</code>, <code>float</code> and <code>fixed64</code> are little-endian. The IQ sample bytes inside <code>IqBlock.samples</code> are big-endian <code>int16</code>. See [[SimTX API/Data types#Conventions|Conventions]].
* '''The server decides.''' The program asks for 4,800 samples per block. <code>argon.simtx.net</code> caps blocks at 40 ms, so at 48,000 samples per second it delivers 1,920. Always use the values in the IqStreamDescriptor. See [[SimTX API/Receiver session#Negotiation|Negotiation]].
* '''Power.''' A sample magnitude of 1.0 is −12 dBm at the receiver input, so a block's mean power in dBm is −12 + 10 × log<sub>10</sub>(mean(I² + Q²)).
* '''Sequence numbers.''' Blocks are numbered from 1. A gap in <code>sequence</code> means the client fell behind and the server dropped blocks.
* '''Rejections are explicit.''' If the server cannot place the receiver, for example because a limit is reached, the SessionStatus says <code>SESSION_STATE_REJECTED</code> with an [[SimTX API/Data types#ErrorCode|ErrorCode]] and a reason, and the server closes the connection.

== Going further ==
* '''Retune''' at any time with a [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]] (member 11): <code>send_frame(sock, 11, f_double(1, 7_074_000.0) + f_varint(2, 1))</code>. The second field is a <code>request_id</code>; the server confirms with a SessionStatus <code>UPDATED</code> carrying it.
* '''Timestamps:''' add <code>f_varint(8, 1)</code> to the ReceiverStart to set <code>timestamped</code>. Every IqBlock then carries the UTC instant of its first sample in fields 3 and 4.
* '''Receive through a station''' instead of an ad-hoc site: sign in, mint a <code>receiver</code> [[SimTX API/Game tickets|game ticket]] for the station, send it in the hello with <code>auth = AUTH_KIND_GAME_TICKET</code>, and set <code>site.station</code> to a [[SimTX API/Data types#StationBinding|StationBinding]]. See [[SimTX API/Stations]].
* '''Transmit:''' transmitting needs an account with <code>game.transmit</code> and one of your stations. [[SimTX API/Transmitter session]] walks through it.

== Next steps ==
* [[SimTX API/Connection and handshake]] explains the hello and its status codes.
* [[SimTX API/Framing]] covers frame sizes and how to skip unknown frames.
* [[SimTX API/Receiver session]] and [[SimTX API/Transmitter session]] cover negotiation, flow control and live updates.
* [[SimTX API/Control session]] adds the station list.
* [[SimTX API/Limits and errors]] explains every error code.

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