TCP protocol

As can be seen in Simulation to Autopilot communication, this TCP communication protocol is used between the Simulator, the hardware_emulator and Autopilots.

Using this protocol, the simulator can interact remotely with autopilots or hardware-emulators running autopilots. The simulator just has to be able to create a TCP connection with the remote autopilot. Here are some use cases:

• The autopilot server-adapter or the hardware-emulator is running locally. The simulator can then connect to it using the localhost address (::1 for IPv6).
• The autopilot server-adapter or the hardware-emulator is running on the local network, use its IP address.
• Open a TCP tunnel using SHH and port forwarding. The simulator then connects to localhost.

Note: Here the term 'server' might be used to describe the remote autopilot or hardware_emulator (since they are started as a TCP server).

Packet format

• 1 byte: packet ID
• 1 short (uint16_t): packet payload length
• length bytes: payload

See network.h file as example.

Packets

Here are the packets used in this protocol.

The specification must match with following files:

• TCPBackend class
• tcp_protocol.h

id	name	Desc.
0	PACKET_END	The simulator is closing the connection directly after this packet is sent.
1	PACKET_ERROR	As payload: An error message.
2	PACKET_INIT	As payload: TimeMode string (measured or realtime)
3	PACKET_INTERFACE	As payload: The DynamicInterface JSON string.
4	PACKET_INPUT_BINARY	See below
5	PACKET_OUTPUT_BINARY	See below
6	PACKET_RUN_CYCLE	Payload: double: delta_sec
7	PACKET_TIME	Payload: double: seconds
8	PACKET_REF_ID	Payload: uint32_t: reference id for the DDC exchange
9	PACKET_PING	No Payload
10	PACKET_REQUEST_CONFIG	No Payload. Request for the PACKET_CONFIG packet from the simulator.
11	PACKET_CONFIG	Payload: JSON string of ComputerProperties.
13	PACKET_INPUT_JSON	See below
14	PACKET_OUTPUT_JSON	See below
15	PACKET_SUSPEND	No Payload. Requests to save the hardware-emulator for later use. Expects a PACKET_EMU_ID as response. The connection is closed after.
16	PACKET_EMU_ID	Payload: Random emulator token (uint32_t). Is sent by the hardware-emulator server when saving an emulator.
17	PACKET_RECONNECT	Payload: Emulator token (uint32_t) from the PACKET_EMU_ID packet. Sent to remote hardware_emulator to re-use a hardware-emulator. Expects remote emulator to respond with PACKET_INTERFACE. This packet replaces the PACKET_INIT to initialize the connection.

The payload for INPUT and OUTPUT packets is structured as follows:

• uint16_t: Port ID (as defined in the DynamicInterface -> Order of appearance)
• Type dependent payload (The result of serializing the data using DataType either for JSON or binary.)

Initialization sequences

The TCPBackend class is responsible to handle this communication on the simulator side.

Connection to a remote autopilot

In this scenario, the remote sever is a server_adapter generated by EMAM2CPP or similar.

• Connect with IP address and port.
• Simulation sends PACKET_INIT with TimeMode config string.
• Simulation sends PACKET_REF_ID with the DDC reference id. (Only used by the DDC-server/ ddc mode)
• Server responds with PACKET_INTERFACE, the DynamicInterface string.
• Repeated Simulation cycles during the simulation (see below)
• Simulation sends PACKET_END to close the connection.

Connection to a remote HardwareEmulator

In this scenario, the remote server code is in hardware_emulator/server.cpp

• Connect with IP address and port.
• Simulation sends PACKET_INIT with hardware as TimeMode config string (this payload is ignored by the remote hardware-emulator, as it will read the exact TimeModel from the PACKET_CONFIG payload).
• Simulation sends PACKET_REF_ID, ignored by hardware-emulator.
• The remote emulator sends a PACKET_REQUEST_CONFIG packet.
• The simulation replies with a PACKET_CONFIG packet, the JSON serialized ComputerProperties.
• Emulator sends PACKET_INTERFACE, the DynamicInterface string.
• Repeated Simulation cycles during the simulation (see below).
• Simulation sends PACKET_END to close the connection.

Suspend/Reconnect to a remote HardwareEmulator

In this scenario the simulation needs to cut and re-establish the connection to a remote hardware-emulator. This happens when vehicles are transferred from one simulator to another in a multi-simulator setup (see server project).

• Suspending
  • When "popping" the vehicle, break the connection by sending the PACKET_SUSPEND packet.
  • The emulator replies with a token inside a PACKET_EMU_ID packet.
  • The connection is closed.
• Reconnecting
  • Connect with IP address and port.
  • Simulation sends PACKET_RECONNECT with the emulator token.
  • Emulator sends PACKET_INTERFACE, the DynamicInterface string.

Simulation cycles

Measured mode

• Sim sends input packets. (multiple PACKET_INPUT_BINARY or PACKET_INPUT_JSON)
• Sim sends run_cycle request. (PACKET_RUN_CYCLE)
• Server runs program.
• Server sends output packets. (multiple PACKET_OUTPUT_BINARY or PACKET_OUTPUT_JSON)
• Server sends exec time -> Simulation continues. (PACKET_TIME)

Realtime mode

This is a concept meant to let the simulator and the hardware running the autopilot run asynchronously. This means the simulator must also run in real-time mode.

This is not implemented.

Sim sends "running" packet when running (with "1" payload)

Sim:

• On Input Event: Send packet
• Async receive output packets -> create events with current time

Server:

• Read input packets
• Run cycle
• Write output packets (with max per second limit?)

Binary or JSON

This protocol supports both JSON and binary serialization for the port data-exchange. The default is binary, JSON is mainly there to allow debugging.

Which one to use is specified by the simulator. Using a flag, it will send the data as binary or JSON. The server/autopilot/emulator is supposed to reply with packets of the same type. (Makes switching the method implicit on the server side).

Note that either mode is supported, so in principle packet modes can be mixed even in the same simulation cycle.