diff --git a/CMakeLists.txt b/CMakeLists.txt index 7636213..18eb7dc 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -23,15 +23,19 @@ set(msg_files "msg/EntityInfo.msg" "msg/EntityState.msg" "msg/NamedPose.msg" + "msg/Resource.msg" "msg/Result.msg" "msg/SimulationState.msg" "msg/SimulatorFeatures.msg" "msg/Spawnable.msg" "msg/TagsFilter.msg" + "msg/WorldResource.msg" ) set(srv_files "srv/DeleteEntity.srv" + "srv/GetAvailableWorlds.srv" + "srv/GetCurrentWorld.srv" "srv/GetEntities.srv" "srv/GetEntitiesStates.srv" "srv/GetEntityBounds.srv" @@ -42,12 +46,14 @@ set(srv_files "srv/GetSimulationState.srv" "srv/GetSimulatorFeatures.srv" "srv/GetSpawnables.srv" + "srv/LoadWorld.srv" "srv/ResetSimulation.srv" "srv/SetEntityInfo.srv" "srv/SetEntityState.srv" "srv/SetSimulationState.srv" "srv/SpawnEntity.srv" "srv/StepSimulation.srv" + "srv/UnloadWorld.srv" ) set(action_files diff --git a/README.md b/README.md index d468902..918135e 100644 --- a/README.md +++ b/README.md @@ -23,3 +23,7 @@ Some interfaces represent optional utility and are considered lower priority: - [GetNamedPoses](srv/GetNamedPoses.srv) - [GetSpawnables](srv/GetSpawnables.srv) - [SetEntityInfo](srv/SetEntityInfo.srv) +- [GetAvailableWorlds](srv/GetAvailableWorlds.srv) +- [LoadWorld](srv/LoadWorld.srv) +- [UnloadWorld](srv/UnloadWorld.srv) +- [GetCurrentWorld](srv/GetCurrentWorld.srv) diff --git a/msg/Resource.msg b/msg/Resource.msg new file mode 100644 index 0000000..e16aeb2 --- /dev/null +++ b/msg/Resource.msg @@ -0,0 +1,7 @@ +# This message is used to specify a resource, either by a URI or by its string content. + +string uri # If uri field is empty, resource_string must not be empty. + +string resource_string # An entity definition file passed as a string, only used if uri is empty. + # If uri field is not empty, resource_string field will be ignored. + # Simulators may support spawning from a file generated on the fly (e.g. XACRO). \ No newline at end of file diff --git a/msg/SimulationState.msg b/msg/SimulationState.msg index 41e3942..24246f7 100644 --- a/msg/SimulationState.msg +++ b/msg/SimulationState.msg @@ -1,16 +1,24 @@ # Simulation states used in SetSimulationState and returned in GetSimulationState -uint8 STATE_STOPPED = 0 # Simulation is stopped, which is equivalent to pausing and resetting with ALL. - # This is typically the default state when simulator is launched. - # Stopped simulation can be played. It can also be paused, which means - # starting simulation in a paused state immediately, - # without any time steps for physics or simulated clock ticks. -uint8 STATE_PLAYING = 1 # Simulation is playing, can be either paused or stopped. -uint8 STATE_PAUSED = 2 # Simulation is paused, can be either stopped (which will reset it) or played. -uint8 STATE_QUITTING = 3 # Closing the simulator application. Switching from STATE_PLAYING or STATE_PAUSED - # states is expected to stop the simulation first, and then exit. - # Simulation interfaces will become unavailable after quitting. - # Running simulation application is outside of the simulation interfaces as - # there is no service to handle the call when the simulator is not up. +uint8 STATE_STOPPED = 0 # Simulation is stopped, which is equivalent to pausing and resetting with ALL_PAUSED. + # This is typically the default state when simulator is launched. + # Stopped simulation can be played. It can also be paused, which means + # starting simulation in a paused state immediately, + # without any time steps for physics or simulated clock ticks. +uint8 STATE_PLAYING = 1 # Simulation is playing, can be either paused or stopped. + +uint8 STATE_PAUSED = 2 # Simulation is paused, can be either stopped (which will reset it) or played. + +uint8 STATE_QUITTING = 3 # Closing the simulator application. Switching from STATE_PLAYING or STATE_PAUSED + # states is expected to stop the simulation first, and then exit. + # Simulation interfaces will become unavailable after quitting. + # Running simulation application is outside of the simulation interfaces as + # there is no service to handle the call when the simulator is not up. + +uint8 STATE_NO_WORLD = 4 # Simulation world is currently unloaded. + # The simulation is inactive and cannot be started, stopped, or paused. + +uint8 STATE_LOADING_WORLD = 5 # Simulation world is currently loading. + # The simulation is inactive while world is loading and cannot be started, stopped, or paused. uint8 state diff --git a/msg/SimulatorFeatures.msg b/msg/SimulatorFeatures.msg index 023c80d..2ea1ce3 100644 --- a/msg/SimulatorFeatures.msg +++ b/msg/SimulatorFeatures.msg @@ -31,6 +31,12 @@ uint8 STEP_SIMULATION_MULTIPLE = 32 # Supports multi-stepping through simu # service or through SimulateSteps action. uint8 STEP_SIMULATION_ACTION = 33 # Supports SimulateSteps action interface. +uint8 WORLD_LOADING = 40 # Supports LoadWorld interface +uint8 WORLD_RESOURCE_STRING = 41 # Supports LoadWorld resource_string field +uint8 WORLD_TAGS = 42 # Supports world tags and tag filtering +uint8 WORLD_UNLOADING = 43 # Supports UnloadWorld interface +uint8 WORLD_INFO_GETTING = 44 # Supports GetCurrentWorld interface +uint8 AVAILABLE_WORLDS = 45 # Supports GetAvailableWorlds interface uint16[] features # A list of simulation features as specified by the list above. diff --git a/msg/Spawnable.msg b/msg/Spawnable.msg index c89eae2..2b53106 100644 --- a/msg/Spawnable.msg +++ b/msg/Spawnable.msg @@ -1,5 +1,7 @@ # Robot or other object which can be spawned in simulation runtime. -string uri # URI which will be accepted by SpawnEntity service. +Resource entity_resource # The resource (e.g. URDF, SDF) for the model to be spawned. + string description # Optional description for the user, e.g. "robot X with sensors A,B,C". + Bounds spawn_bounds # Optional spawn area bounds which fully encompass this object. diff --git a/msg/WorldResource.msg b/msg/WorldResource.msg new file mode 100644 index 0000000..8061e86 --- /dev/null +++ b/msg/WorldResource.msg @@ -0,0 +1,15 @@ +# World is a virtual environment in which the simulation happens. +# Worlds are also known as scenes or levels in some simulators. +# Depending on the world format, loading of a world might be associated with changes +# in certain parameters, including physics settings such as gravity. +# World resources may be defined in standard or simulation-specific formats, +# and, depending on the simulator, loaded from local or remote repositories. + + +string name # World name, which is not necessarily unique. + +Resource world_resource # The resource for the world to be loaded. + +string description # Optional custom description of the world + +string[] tags # Optional tags describing the world (e.g., "indoor", "outdoor", "warehouse") diff --git a/package.xml b/package.xml index e6d4e14..f9c7d22 100644 --- a/package.xml +++ b/package.xml @@ -2,7 +2,7 @@ simulation_interfaces - 1.0.1 + 2.0.0 A package containing simulation interfaces including messages, services and actions Adam Dabrowski Apache License 2.0 diff --git a/srv/GetAvailableWorlds.srv b/srv/GetAvailableWorlds.srv new file mode 100644 index 0000000..9b58452 --- /dev/null +++ b/srv/GetAvailableWorlds.srv @@ -0,0 +1,23 @@ +# Return a list of available world resources which can be used with LoadWorld. +# Support for this interface is indicated through the AVAILABLE_WORLDS value in GetSimulatorFeatures. +# By default, a simulator will search its default local and online sources. If some +# default sources can't be accessed (e.g. due to connectivity issues), the +# DEFAULT_SOURCES_FAILED error result code will be returned. + +string[] additional_sources # Optional field for additional sources (local or remote) to search, + # specified as standard URIs if possible. + +TagsFilter filter # Only get worlds with tags matching the filter. The filter is optional and matches everything by default. + # This feature is supported if WORLD_TAGS feature is included in output of GetSimulatorFeatures. + +bool offline_only # If true, only offline/local sources should be searched. Defaults to false. + +bool continue_on_error # If true, the simulator will continue to search sources even if some fail. + # The service will return success if any source yielded worlds. Defaults to false. +--- + +uint8 DEFAULT_SOURCES_FAILED = 101 # Some default sources could not be accessed. + +Result result # Standard result message. A specific result code should be used if some sources were not accessible. + +WorldResource[] worlds # Available world resources. diff --git a/srv/GetCurrentWorld.srv b/srv/GetCurrentWorld.srv new file mode 100644 index 0000000..7ade9b3 --- /dev/null +++ b/srv/GetCurrentWorld.srv @@ -0,0 +1,10 @@ +# Get information about the currently loaded world in the simulation. +# Support for this interface is indicated through the WORLD_INFO_GETTING value in GetSimulatorFeatures. + +--- + +uint8 NO_WORLD_LOADED = 101 # No world is loaded at the moment. + +Result result # Standard result message + +WorldResource world # Information about the currently loaded world. Only valid if result is RESULT_OK. diff --git a/srv/LoadWorld.srv b/srv/LoadWorld.srv new file mode 100644 index 0000000..c4736d4 --- /dev/null +++ b/srv/LoadWorld.srv @@ -0,0 +1,29 @@ +# Load a simulation world from a file or resource. +# This means clearing the current scene (removing all entities), loading the new world and setting the simulation to the stopped state. +# Support for this interface is indicated through the WORLD_LOADING value in GetSimulatorFeatures. +# resource_string field support is indicated through the WORLD_RESOURCE_STRING value in GetSimulatorFeatures. +# Currently loaded worlds will be unloaded before attempting to load a new one. +# Any previously spawned entities will be removed. Once a world is loaded, simulation will be left in a Stopped state. + +string uri # Resource such as SDF, USD, MJCF, or other simulator-native format world file. + +string resource_string # Simulation world passed as a string. This field is used if the uri field is empty. + +bool fail_on_unsupported_element # Fail on unsupported elements (such as SDFormat sub-tags). By default, such elements are ignored. + + +bool ignore_missing_or_unsupported_assets # Ignore missing or unsupported assets. By default, missing or unsupported assets result in failure. + +--- + +uint8 UNSUPPORTED_FORMAT = 101 # Format for uri or resource string is unsupported. +uint8 NO_RESOURCE = 102 # Both uri and resource string are empty. +uint8 RESOURCE_PARSE_ERROR = 103 # Resource file or string failed to parse. +uint8 MISSING_ASSETS = 104 # At least one of resource assets (such as meshes) was not found. +uint8 UNSUPPORTED_ASSETS = 105 # At least one of resource assets (such as meshes) is not supported. +uint8 UNSUPPORTED_ELEMENTS = 106 # At least one of world definition elements such as format tags is unsupported. + + +Result result # Standard result message + +WorldResource world # Information about the loaded world. Only valid if result is RESULT_OK. diff --git a/srv/SpawnEntity.srv b/srv/SpawnEntity.srv index 0e76c10..cab2afa 100644 --- a/srv/SpawnEntity.srv +++ b/srv/SpawnEntity.srv @@ -11,15 +11,13 @@ string name # A name to give to the spawned entity. bool allow_renaming # Determines whether the spawning succeeds with a non-unique name. # If it is set to true, the user should always check entity_name response field # and use it for any further interactions. -string uri # Resource such as SDFormat, URDF, USD or MJCF file, a native prefab, etc. - # Valid URIs can be determined by calling GetSpawnables first, and you can check - # the simulator format support by reading SimulatorFeatures spawn_formats field. - # If uri field is empty, resource_string must not be empty. -string resource_string # An entity definition file passed as a string. - # Simulators may support spawning from a file generated on the fly (e.g. XACRO). - # It is supported by your simulator if GetSimulatorFeatures includes - # SPAWNING_RESOURCE_STRING feature. - # If uri field is not empty, resource_string field will be ignored. + +Resource entity_resource # Resource such as SDFormat, URDF, USD or MJCF file, a native prefab, etc. + # Valid URIs can be determined by calling GetSpawnables first. + # Check simulator format support via the spawn_formats field in GetSimulatorFeatures. + # Using resource_string is supported if GetSimulatorFeatures includes + # the SPAWNING_RESOURCE_STRING feature. + string entity_namespace # Spawn the entity with all its interfaces under this namespace. geometry_msgs/PoseStamped initial_pose # Initial entity pose. # The header contains a reference frame, which defaults to global "world" frame. diff --git a/srv/UnloadWorld.srv b/srv/UnloadWorld.srv new file mode 100644 index 0000000..aa04752 --- /dev/null +++ b/srv/UnloadWorld.srv @@ -0,0 +1,9 @@ +# Unload the current simulation world. +# Support for this interface is indicated through the WORLD_UNLOADING value in GetSimulatorFeatures. +# Any previously spawned entities will be removed. + +--- + +uint8 NO_WORLD_LOADED = 101 # No world is loaded at the moment. + +Result result # Standard result message