Skip to content

Command response format

Jump to bottom
William Setterberg edited this page May 31, 2026 · 1 revision

The IMPISH command response is defined in command-executor.rs. It is a byte-level format and relies on the "group separator" character (ASCII 0x1D) for delineating different sections. We define here the command response and its packetizing procedure.

There is no error checking in the definition; we rely on the IP header checksum and network layers below our program to do error checking.

Types are indicated using the Rust conventions.

Base response definition

There are a few sections in the command response:

  • Command exit code (u8)
  • Command that was run (variable length u8)
  • Command stdout (variable length u8)
  • Command stderr (variable length u8)

Between each section is an ASCII 0x1D character.

Packetized response definition

After the full response is constructed as above, the response is packetized into fixed-size chunks. The chunks are sent as UDP packets. Each chunk has the following format:

  • A fraction of the payload (base response): 512B = [u8; 512].
    • If the payload fraction is shorter than 512B, the segment is zero-padded at the end.
  • UNIX timestamp from when the packetizing started (u32)
  • Command counter, i.e. the number received since program started (u16)
  • The packet ordering number for the current response (u16)
  • The total number of packets that will be in the response (u16)

Each packetized response is therefore 522B = [u8; 522]. This is significantly smaller than the MTU of 9100B on the gondola network, and should be small enough to transmit across the broader internet with no fragmentation.

The metadata (total expected packets, current packet number, command counter, timestamp) allows for reconstruction of partial packet replies on the ground. Sometimes we only receive partial responses.

There is a soft limit of $2^{16} - 1$ packets per command response. If more packets are sent in a response than can be enumerated in a u16, more complicated logic will be required to sort them out.

Known issues

Some commands like tree will use nonprintable characters, or compositions of characters, to do things like change the text color or styling. These can disrupt the command executor formatting by introducing 0x1D characters where they don't really belong. Sometimes, the executor will get stuck processing the output of such a command.

As of May 2026, the solution is to just avoid any command that has strange character outputs. If the executor hangs, restart its systemd service.

Clone this wiki locally