|
|
As can be seen in [Simulation to Autopilot communication](/dev-docs/autopilots/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](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/shared_cpp/-/blob/master/network.h) as example.
|
|
|
|
|
|
## Packets
|
|
|
|
|
|
Here are the packets used in this protocol.
|
|
|
|
|
|
The specification must match with following files:
|
|
|
|
|
|
- [TCPBackend class](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/hardware_emulator/-/blob/master/src/main/java/de/rwth/montisim/hardware_emulator/computer/TCPBackend.java)
|
|
|
- [tcp_protocol.h](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/shared_cpp/-/blob/master/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](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/commons/-/blob/master/src/main/java/de/rwth/montisim/commons/dynamicinterface/DataType.java) either for JSON or binary.)
|
|
|
|
|
|
## Initialization sequences
|
|
|
|
|
|
The [TCPBackend class](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/hardware_emulator/-/blob/master/src/main/java/de/rwth/montisim/hardware_emulator/computer/TCPBackend.java) 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](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/generators/EMAM2Cpp/-/blob/master/src/main/resources/template/dynamic_interface/server_adapter.cpp.ftl) 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](https://git.rwth-aachen.de/monticore/EmbeddedMontiArc/simulators/hardware_emulator/-/blob/master/hardware_emulator/src/server/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. |
|
|
\ No newline at end of file |