Skip to main content

Protocols, commands & UDP — how they fit together

AutoSat speaks to a spacecraft as protobuf messages over UDP. You define the message formats once (a protocol), bind them to a satellite, and then send them as commands and receive them as telemetry. This page covers how to wire those pieces up.

The pieces​

  • Protocol — a named bundle of your .proto definitions, uploaded as immutable versions. This is your message catalog: every message type you send or receive lives here.
  • Satellite — the binding point. Each satellite carries an IP address, a default port, and an active protocol version. These three fields decide where commands are sent and how incoming packets are decoded.
  • Command — an outbound message. A command with a protobuf format names a protocol version + message type, and maps its arguments onto that message's fields.
  • Ground station — where an agent runs. Its UDP ports are the inbound listeners; commands you send are routed out through the ground station selected in the console.

1. Define a protocol​

On the Protocols page, create a protocol and upload a version. A version is a zip of your .proto files plus the entrypoint file (the one whose import statements pull in the rest). Imports are resolved inside the bundle, so ship every file the entrypoint references.

Versions are immutable. To change a message format, upload a new version and point the satellite at it — existing history stays decodable against the version it was captured with.

2. Bind the protocol to a satellite​

On the satellite's settings, set:

  • Active protocol version — used both to validate outbound commands and to decode inbound packets for this satellite.
  • IP address — does double duty. It is the default destination for commands, and it is how inbound packets are attributed: a received packet's source IP is matched against this field to decide which satellite (and therefore which protocol version) it belongs to.
  • Default port — the default destination port for commands sent to this satellite.

3. Define commands (outbound)​

Give the command a protobuf format: pick the protocol version and the message type to send, then declare arguments whose names match the proto field names. Argument values are coerced to the field's type (integers, floats, booleans, enums and repeated fields are all handled).

The command's destination is optional:

  • Leave host/port empty and the command resolves to the target satellite's IP address and default port — so the same command works against any satellite it's run on.
  • Set host and/or port explicitly to override (e.g. a fixed simulator endpoint).

A command may be satellite-level or scoped to a subsystem — that only affects who sees it and how it's grouped, not how it's encoded.

4. Add UDP listeners on the ground station (inbound)​

Add the UDP ports the spacecraft (or your simulator) will downlink to. The agent running for that ground station binds those ports and listens for packets. An agent reads its ports when it connects, so set them before starting the agent — reconnect it after changing them.

How a command goes out​

  1. You run the command in a console, with a ground station selected.
  2. The server validates the args, encodes the chosen protobuf message, and resolves the destination (command host/port, else the satellite's IP / default port).
  3. It hands the encoded packet to the selected ground station's agent.
  4. The agent transmits it as a UDP datagram to the destination.
tip

An agent running in DRY_RUN mode echoes the encoded bytes (message type, destination, size, hex) back to the console instead of transmitting — handy for checking your field mappings before anything hits the wire.

How telemetry comes in​

  1. A packet arrives on one of the ground station's UDP ports.
  2. The agent forwards it to the server with the packet's source IP.
  3. The server matches that source IP to a satellite (by the satellite's IP address) and decodes the bytes with that satellite's active protocol version.
  4. The decoded message appears in that satellite's console.
warning

Inbound packet decoding is driven by telemetry processors. Each processor selects the protobuf message type it expects, and AutoSat decodes packets for that satellite against those configured types. Declaration order in the .proto file does not select the inbound message.

For how decoded messages become named, plottable values, see Telemetry.

When a packet won't decode​

The console shows a decode failure when:

  • No satellite matches the source IP — check the sender's address against the satellite's IP-address field. (Note the matching is by source IP, not the port the packet arrived on.)
  • The matched satellite has no active protocol version — set one in step 2.
  • The bytes don't fit any message type selected by telemetry processors for the satellite's active protocol version.