Service API¶
ServiceAPI¶
Frame Synchronization and Callback Functions¶
Frame Synchronization in the SimOne system is based on Virtual Time using Logical Frames, meaning all operations in the system proceed frame by frame:
(1) Concept of Frame Synchronization:
- Every action in the system depends on the execution of Logical Frames.
- The execution time of a single frame in real-world time can be very short (e.g., 0.00001 seconds) or very long (e.g., 100000 seconds), decoupled from real time.
- Through frame-based time control, the running speed of the simulation system can be flexibly adjusted, such as accelerating or slowing down Use Case execution.
(2) Methods for obtaining SimOne data:
- Callback: When the system has new data, it notifies the user via a registered callback function to retrieve the data.
- Active Query API: Users can actively call APIs (e.g.,
GetGps) to retrieve data for the current frame. If the system frame has not advanced, successive calls will return the same data.
(3) Combining Frame Synchronization and data retrieval:
- Using the Frame Synchronization API, you can control the runtime of SimOne system Use Cases. Within a given frame, no matter how many times you call data retrieval APIs, the data will be the same.
- If Frame Synchronization is not used, directly calling APIs or using Callback functions to retrieve data is more straightforward and is suitable for Use Cases that only need to obtain scene data.
Select Vehicle and Initialize¶
Note
This operation allows you to set whether to use the Frame Synchronization feature
-
Frame Synchronization (ensures real-time performance and stability)
-
Non-Frame Synchronization (improves runtime efficiency)
| Event | API |
|---|---|
| Initialize SimOne API | SIMONE_API bool InitSimOneAPI(const char mainVehicleId = "0", bool isFrameSync = false, const char serverIP = "127.0.0.1", int port = 23789, void(startCase)()=0, void(endCase)()=0, int registerNodeId=0); |
| Multi-vehicle version - Initialize SimOne API | SIMONE_API bool InitSimOneAPIEx(char mainVehicleIdList, int count, bool isFrameSync = false, const char serverIP = "127.0.0.1", int port = 23789, void(startCase)() = 0, void(*endCase)() = 0, int registerNodeId = 0); |
| Initialize SimOne API with Timeout | SIMONE_API bool InitSimOneAPIWithTimeOut(const char mainVehicleId = "0", bool isFrameSync = false, const char serverIP = "127.0.0.1", int port = 23789, int timeOutMS = -1, void(startCase)() = 0, void(endCase)() = 0, int registerNodeId = 0); |
| Multi-vehicle version - Initialize SimOne API with Timeout | SIMONE_API bool InitSimOneAPIExWithTimeOut(char mainVehicleIdList, int count, bool isFrameSync = false, const char serverIP = "127.0.0.1", int port = 23789, int timeOutMS = -1, void(startCase)() = 0, void(*endCase)() = 0, int registerNodeId = 0); |
| Parameter | Description |
|---|---|
| mainVehicleId | Ego Vehicle ID (range: 0 to 9) |
| isFrameSync | Whether to enable frame synchronization |
| serverIP | BridgeIO server IP address |
| port | BridgeIO server port number |
| startCase | Callback function called before the Use Case starts |
| endCase | Callback function called after the Use Case ends |
| registerNodeId | Register Node ID (Reserved parameter for future use) |
| count | Number of Ego Vehicle IDs |
| timeOutMS | Timeout duration, in milliseconds |
Get Ego Vehicle Status¶
| Event | API |
|---|---|
| Active Query Ego Vehicle status | SIMONE_API bool GetMainVehicleStatus(const char mainVehicleId, SimOne_Data_MainVehicle_Status pMainVehicleStatus); |
| Callback to get Ego Vehicle status | SIMONE_API bool SetMainVehicleStatusUpdateCB(void(cb)(const char mainVehicleId, SimOne_Data_MainVehicle_Status *pMainVehicleStatus)); |
| Parameter | Description |
|---|---|
| mainVehicleId | Ego Vehicle ID |
| pMainVehicleStatus | Pointer to the Ego Vehicle status data |
SimOne_Data_MainVehicle_Status structure description:
| Parameter | Description |
|---|---|
| mainVehicleId | Queue of Ego Vehicle IDs |
| mainVehicleStatus | Corresponding status |
Other Function Descriptions¶
| Category | Event | API |
|---|---|---|
| Exit | Exit API Node | SIMONE_API bool TerminateSimOneAPI(); |
| Get Use Case Information | Get Use Case details | SIMONE_API bool GetCaseInfo(SimOne_Data_CaseInfo *pCaseInfo); |
| Get Use Case run status | SIMONE_API ESimOne_Case_Status GetCaseRunStatus(); | |
| Get Ego Vehicle list | SIMONE_API bool GetMainVehicleList(SimOne_Data_MainVehicle_Info *pMainVehicleInfo); | |
| Get HD map metadata | SIMONE_API bool GetHDMapData(SimOne_Data_Map* hdMap); | |
| Get current library version number | SIMONE_API const char *GetVersion(); | |
| Case Control | Wait and get current frame value | SIMONE_API int Wait(); |
| Advance to next frame | SIMONE_API void NextFrame(int frame); //frame is the specific frame number | |
| Pause, used for non-Frame Synchronization debugging | SIMONE_API int Pause(); | |
| Continue, used for non-Frame Synchronization debugging | SIMONE_API int Continue(); | |
| Auto Callback Frame Data | Callback function for each frame in the simulation scene | SIMONE_API bool SetFrameCB(void(*FrameStart)(int frame), void(*FrameEnd)(int frame)); |
| Intercept Node Information | Node communication data send API | SIMONE_API bool SendRouteMessage(int length, void* pBuffer, int msgId, int toNodeId, ESimOne_Client_Type toNodeType); |
| Node communication data receive API | SIMONE_API bool ReceiveRouteMessageCB(void(*cb)(int fromId, ESimOne_Client_Type fromType, int length, const void* pBuffer, int commandId)); | |
| Set Log Format | Log configuration interface | SIMONE_API bool SetLogOut(ESimOne_LogLevel_Type level, const char *format, ...); |
SimOne_Data_CaseInfo is as follows:
| Parameter | Description |
|---|---|
| caseName | Use Case name |
| caseId | Use Case ID |
| taskId | Task ID |
SimOne_Data_MainVehicle_Info structure is as follows:
| Parameter | Description |
|---|---|
| size | Number of vehicles |
| id_list | Vehicle ID |
| type_list | Vehicle type |
SimOne_Data_Map structure is as follows:
| Parameter | Description |
|---|---|
| openDrive | Map name |
| openDriveUrl | URL for map download |
| opendriveMd5 | MD5 value of the map file |