Editing SimTX API v24/Quick start (section)

== Receiving ==
The program below connects to the public server, completes an anonymous [[SimTX API v24/Packets/Handshake|handshake]], requests a receiver on 7.1 MHz in Budapest, and prints the power of the first ten IQ blocks.

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

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


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 write_utf(s):
    data = s.encode("utf-8")  # fine for ASCII; see Data types for modified UTF-8
    return struct.pack(">H", len(data)) + data


def read_utf(sock):
    (n,) = struct.unpack(">H", read_exact(sock, 2))
    return read_exact(sock, n).decode("utf-8", "replace")


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)

# Handshake: magic, version, role 1 (RECEIVER), authKind 0 (ANONYMOUS), empty credential
sock.sendall(struct.pack(">iibb", 0x53494D54, 24, 1, 0) + write_utf(""))

packet_id, status = struct.unpack(">BB", read_exact(sock, 2))
assert packet_id == 30, packet_id
message = read_utf(sock)
if read_exact(sock, 1)[0]:
    read_exact(sock, 16)  # account UUID
read_utf(sock)  # handle
read_utf(sock)  # display name
for _ in range(read_exact(sock, 1)[0]):
    read_utf(sock)  # permission
read_exact(sock, 16)  # authorizationRevision, leaseExpiresAtEpochMillis
if status != 0:
    raise SystemExit(f"handshake rejected ({status}): {message}")

# ReceiverSessionRequest
antenna = write_utf("DIPOLE") + struct.pack(">ffffi", 10.0, 0.0, 0.0, 0.0, 0)
request = (
    write_utf("N0CALL")
    + struct.pack(">ddd", 47.4979, 19.0402, 120.0)
    + antenna
    + struct.pack(">fffii", 5.0, 7_100_000.0, 48_000.0, 48_000, 4_800)
    + write_utf("")
)
sock.sendall(b"\x01" + request)

packet_id = read_exact(sock, 1)[0]
assert packet_id == 1, packet_id
rate, center, chunk, fmt = struct.unpack(">ifib", read_exact(sock, 13))
print(f"stream: {rate} S/s at {center:.0f} Hz, {chunk} samples/block, format {fmt}")

width = 2 if fmt == 1 else 1
full_scale = 32767 if fmt == 1 else 127
for _ in range(10):
    packet_id = read_exact(sock, 1)[0]
    assert packet_id == 2, packet_id
    (length,) = struct.unpack(">i", read_exact(sock, 4))
    payload = read_exact(sock, length)
    (scale,) = struct.unpack(">f", payload[:4])
    code = ">%dh" % (chunk * 2) if fmt == 1 else ">%db" % (chunk * 2)
    raw_iq = struct.unpack(code, payload[4:])
    power = sum((v * scale / full_scale) ** 2 for v in raw_iq) / chunk
    print(f"block: {length} bytes, scale {scale:.4g}, mean power {power:.3e}")

sock.close()
</syntaxhighlight>

Typical output:

<syntaxhighlight lang="text">
stream: 48000 S/s at 7100000 Hz, 1920 samples/block, format 1
block: 7684 bytes, scale 0.0009043, mean power 1.337e-07
block: 7684 bytes, scale 0.0009922, mean power 1.366e-07
...
</syntaxhighlight>

Things to notice:
* The program asked for 4,800 samples per block and received 1,920. The server decides; the [[SimTX API v24/Packets/IqStreamDescriptor|IqStreamDescriptor]] says what it decided. See [[SimTX API v24/Receiver session#Negotiation|Negotiation]].
* A mean power of about 1.3 × 10<sup>−7</sup> is −12 + 10·log<sub>10</sub>(1.3 × 10<sup>−7</sup>) ≈ '''−81 dBm''': mostly the 40 m band's background noise in a 48 kHz bandwidth. Tune to a frequency where someone is transmitting and it rises.
* <code>HOST</code> and <code>PORT</code> are hard-coded for brevity. Real software should take them from the [[SimTX API v24/Server directory|server directory]] or from its configuration.

To feed the samples to a demodulator, convert each block into complex values (<code>I + jQ</code>, scaled as shown) and pass them on. To change frequency, send <code>b"\x0d" + struct.pack(">f", new_frequency_hz)</code> at any time.