### Install Launch Files Source: https://github.com/avidbots/flatland/blob/master/flatland_server/CMakeLists.txt Installs launch files to the share destination. Ensure CATKIN_PACKAGE_SHARE_DESTINATION is correctly defined. ```cmake install(DIRECTORY launch DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION} ) ``` -------------------------------- ### Build Flatland Stack and Source Setup Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/flatland_tutorials/create_plugin.md Compile the Flatland stack and source the setup file to make ROS packages available. This is essential for using Flatland and its tools. ```bash catkin_make ``` ```bash source devel/setup.bash ``` -------------------------------- ### Install Plugins File Source: https://github.com/avidbots/flatland/blob/master/flatland_server/CMakeLists.txt Installs the flatland_plugins.xml file to the share destination. This file likely contains plugin definitions for Flatland. ```cmake install(FILES flatland_plugins.xml DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION} ) ``` -------------------------------- ### Install Python Script Source: https://github.com/avidbots/flatland/blob/master/flatland_server/CMakeLists.txt Installs the map_to_lines.py script to the binary destination. This makes the script executable from the system's PATH. ```cmake install(PROGRAMS scripts/map_to_lines.py DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION} ) ``` -------------------------------- ### Run Flatland Simulator Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/flatland_tutorials/create_plugin.md Launch the Flatland simulator. This command starts the core simulation environment. ```bash roslaunch flatland_server server.launch ``` -------------------------------- ### Install Test Directory Source: https://github.com/avidbots/flatland/blob/master/flatland_server/CMakeLists.txt Installs the conestogo_office_test directory to the test subdirectory of the share destination. This is typically used for test-related assets. ```cmake install(DIRECTORY test/conestogo_office_test DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION}/test ) ``` -------------------------------- ### ROS Parameter Evaluation Examples Source: https://github.com/avidbots/flatland/blob/master/docs/core_functions/yaml_preprocessor.md Illustrates using the `param()` Lua function within $eval expressions to fetch ROS parameters. Examples show handling unset parameters with defaults and performing arithmetic operations with retrieved values. ```yaml # in: (rosparam /test/param not set) foo: $eval param("/test/param", 0)/2.0 # out: foo: 0 ``` ```yaml # in: (rosparam /test/param set to 5.0) foo: $eval param("/test/param", 0)/2.0 + 1 # out: foo: 2.5 ``` -------------------------------- ### Turtlebot Model Configuration Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/core_functions/models.md Example YAML configuration for a turtlebot model in Flatland. Defines multiple bodies with different footprint types and properties. ```yaml # required, list of bodies of the model, must have at least one body bodies: # required, name of the body, must be unique within the model - name: base_link # optional, default true. If false (see yaml preprocessor for details), this body is skipped enabled: true # optional, defaults to [0, 0, 0], in the form of [x, y, theta] w.r.t the # model pose specified in world yaml. Pose is simply the initial pose # of the body, it does not add additional constrains in any way pose: [0, 0, 0] # optional, default to dynamic, must be one of dynamic, static, kinematic, # these are consistent with Box2D's body types type: dynamic # optional, default to [1 ,1, 1, 0.5], in the form of [r, g, b, alpha], # for visualization color: [1, 1, 1, 0.5] # optional, defaults to 0.0, specifies the Box2D body linear damping linear_damping: 0 # optional, defaults to 0.0, specifies the Box2D body angular damping angular_damping: 0 # required, list of footprints for the body, you can have any number of # footprints footprints: # required, type of footprint, valid options are circle and polygon - type: circle # required, radius of the circle footprint, only used for circle type radius: 0.5 # optional, defaults to [0, 0], in the form of [x, y] w.r.t the origin # of the body, only used for circle type center: [0.0, 0.0] # optional, defaults to ["all"], a list of layers specifying which # layer the footprint belongs to, collisions/contacts only occurs # between objects in the same layer, used for all footprint types layers: ["all"] # optional, defaults to true # If set to "false" entirely disables collision with this object # Does not disable interactions like the laser scan plugin. collision: true # required, the density of footprint in kg/m^2 in Box2D, used for all # footprint types density: 1 # optional, default to 0.0, specifies Box2D fixture friction, used for # all footprint types friction: 0 # optional, default to 0.0, specifies Box2D fixture restitution, used # for all footprint types restitution: 0 # optional, default to false, whether to set as Box2D sensor, sensor # detects collisions/contacts but does not have responses, used for # all footprint types sensor: false # body for the rear wheel - name: rear_wheel footprints: # an example for polygon type - type: polygon # required, vertices for polygon, 3 <= length <= 8 (limited by Box2D), # in the form of [x, y] coordinates w.r.t body origin, only used for # polygon type points: [[-0.05, -0.05], [-0.05, 0.05], [0.05, 0.05], [0.05, -0.05]] density: 1 # body for left wheel - name: left_wheel footprints: - type: polygon points: [[-.125, -0.05], [-.125, 0.05], [.125, 0.05], [.125, -0.05]] density: 1 # body for right wheel, notice how left wheel and right wheel are the same # they will be spawned in the same location with pose [0, 0, 0] by default, # joints need to be used to snap them in place - name: right_wheel footprints: - type: polygon points: [[-.125, -0.05], [-.125, 0.05], [.125, 0.05], [.125, -0.05]] density: 1 ``` -------------------------------- ### Environment Variable Evaluation Examples Source: https://github.com/avidbots/flatland/blob/master/docs/core_functions/yaml_preprocessor.md Demonstrates how to use the `env()` Lua function within $eval expressions to retrieve environment variables, including handling cases where variables are not set and providing default values. ```yaml # in: (SOME_ENV not set) foo: $eval env("SOME_ENV") # out: foo: "" ``` ```yaml # in: (SOME_ENV not set) foo: $eval env("SOME_ENV", false) # out: foo: false ``` ```yaml # in: (export SOME_ENV=true) foo: $eval env("SOME_ENV") # out: foo: true ``` -------------------------------- ### Implement Simple Plugin Logic Source: https://github.com/avidbots/flatland/blob/master/docs/flatland_tutorials/create_plugin.md Implement the OnInitialize method for the Simple plugin to print 'Hello world' to the ROS error stream. ```cpp #include #include #include using namespace flatland_server; namespace flatland_tutorials { void Simple::OnInitialize(const YAML::Node &config) { ROS_ERROR_STREAM("Hello world"); } }; PLUGINLIB_EXPORT_CLASS(flatland_tutorials::Simple, flatland_server::ModelPlugin) ``` -------------------------------- ### Launch Flatland Server with Default Parameters Source: https://github.com/avidbots/flatland/blob/master/docs/core_functions/ros_launch.md Use this command to launch the simulator with default parameters. Specify the world file path. ```bash $ roslaunch flatland_server server.launch world_path:=/path/to/world.yaml ``` -------------------------------- ### Launch Flatland Server with Full Parameters Source: https://github.com/avidbots/flatland/blob/master/docs/core_functions/ros_launch.md This command launches the simulator with all available parameters. Adjust values for update rate, step size, visualization, and map simplification. ```bash $ roslaunch flatland_server server.launch world_path:=/path/to/world.yaml \ update_rate:=200.0 \ step_size:=0.005 \ show_viz:=true \ viz_pub_rate:=30.0 \ use_rviz:=false \ simplify_map:=2 ``` -------------------------------- ### Create Flatland Workspace Source: https://github.com/avidbots/flatland/blob/master/docs/flatland_tutorials/create_plugin.md Set up the necessary directories for your Flatland ROS workspace. ```bash mkdir flatland_ws cd flatland_ws/ ``` ```bash mkdir src cd src ``` ```bash git clone https://github.com/avidbots/flatland.git cd .. ``` ```bash catkin_make ``` ```bash source devel/setup.bash ``` ```bash roslaunch flatland_server server.launch ``` -------------------------------- ### Flatland Plugin Implementation File Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/flatland_tutorials/create_plugin.md Implement the Simple plugin's OnInitialize method to print 'Hello world' to ROS_ERROR_STREAM. This code defines the plugin's behavior. ```cpp #include #include #include using namespace flatland_server; namespace flatland_tutorials { void Simple::OnInitialize(const YAML::Node &config) { ROS_ERROR_STREAM("Hello world"); } }; PLUGINLIB_EXPORT_CLASS(flatland_tutorials::Simple, flatland_server::ModelPlugin) ``` -------------------------------- ### Define Custom Robot Model in YAML Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/flatland_tutorials/custom_robot.md Use this YAML structure to define a robot's bodies, types, colors, and footprints. This example shows a dynamic body with a polygonal footprint. ```yaml bodies: - name: base type: dynamic color: [1, 1, 1, 1] footprints: - type: polygon density: 100 points: [ [-1.03, -0.337], [.07983, -0.337], [.30, -.16111], [.30, .16111], [.07983, 0.337], [-1.03, 0.337] ] ``` -------------------------------- ### Create ROS Workspace and Clone Flatland Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/flatland_tutorials/create_plugin.md Set up a ROS workspace and clone the Flatland stack. This is the initial step for building ROS-dependent projects. ```bash mkdir flatland_ws cd flatland_ws/ ``` ```bash mkdir src cd src ``` ```bash git clone https://github.com/avidbots/flatland.git cd .. ``` -------------------------------- ### Launch Flatland Simulation with ROS Parameters Source: https://context7.com/avidbots/flatland/llms.txt This bash script demonstrates how to set environment variables and ROS parameters before launching the Flatland server. This is useful for configuring the simulation environment dynamically at runtime. ```bash # Launch with parameters export ENABLE_LIDAR=true export SENSOR_TYPE=lidar rosparam set /robot/radius 0.3 rosparam set /laser/max_range 25 roslaunch flatland_server server.launch world_path:=/path/to/world.yaml ``` -------------------------------- ### Resolve TF Frame IDs with Model Namespace Source: https://github.com/avidbots/flatland/blob/master/docs/core_functions/model_plugins.md Prepend the model's namespace to TF frame IDs to avoid conflicts, especially for frames on the model. Handles frames starting with '/' by stripping the leading slash. ```cpp tf::resolve(GetModel()->NameSpaceTF(frame_id)); ``` -------------------------------- ### Launch Flatland Server Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/quick_start.md Launch the Flatland simulation server using ROS. Specify the path to the world configuration file. ```bash $ roslaunch flatland_server server.launch world_path:=/path/to/world.yaml ``` -------------------------------- ### Launch Flatland Server with Custom World Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/flatland_tutorials/custom_robot.md Launch the Flatland simulator with your custom world file by providing the `world_path` override. Ensure the path points to your custom world YAML file. ```bash roslaunch flatland_server.launch world_path:=/home/mikeb/Dev/flatland_ws/src/flatland/flatland_server/test/conestogo_office_test/your_custom_world.yaml ``` -------------------------------- ### Launch Flatland Server with ROS Source: https://context7.com/avidbots/flatland/llms.txt Launches the Flatland simulation server node. Use the 'world_path' parameter to specify the simulation environment configuration. Additional parameters control simulation rate, physics step size, visualization, and map simplification. ```bash roslaunch flatland_server server.launch world_path:=/path/to/world.yaml ``` ```bash roslaunch flatland_server server.launch world_path:=/path/to/world.yaml \ update_rate:=200.0 \ step_size:=0.005 \ show_viz:=true \ viz_pub_rate:=30.0 \ use_rviz:=false \ simplify_map:=2 ``` -------------------------------- ### Flatland CMakeLists.txt Source: https://github.com/avidbots/flatland/blob/master/flatland/CMakeLists.txt This is the main CMakeLists.txt file for the Flatland metapackage. It specifies the minimum CMake version and project name, and finds the catkin package. ```cmake cmake_minimum_required(VERSION 3.0.2) project(flatland) find_package(catkin REQUIRED) catkin_metapackage() ``` -------------------------------- ### Define Simple Plugin Header Source: https://github.com/avidbots/flatland/blob/master/docs/flatland_tutorials/create_plugin.md Declare the Simple plugin class, inheriting from flatland_server::ModelPlugin and defining the OnInitialize method. ```cpp #include #ifndef FLATLAND_PLUGINS_SIMPLE_H #define FLATLAND_PLUGINS_SIMPLE_H using namespace flatland_server; namespace flatland_tutorials { class Simple : public ModelPlugin { public: void OnInitialize(const YAML::Node &config) override; }; }; #endif ``` -------------------------------- ### Configure Flatland World with Dynamic Parameters Source: https://context7.com/avidbots/flatland/llms.txt This YAML configuration demonstrates how to dynamically set model properties like 'enabled' status, 'radius', and 'density' using environment variables and ROS parameters. It also shows how to conditionally enable components based on environment settings. ```yaml bodies: - name: base # Enable/disable based on environment variable enabled: $eval env("ENABLE_BASE", true) pose: [0, 0, 0] footprints: # Dynamic radius from rosparam - type: circle radius: $eval param("/robot/radius", 0.5) density: $eval param("/robot/mass", 10) / (3.14159 * param("/robot/radius", 0.5)^2) - name: front_sensor # Conditionally enable sensor enabled: | $eval if env("SENSOR_TYPE", "lidar") == "lidar" then return true else return false end plugins: - type: Laser enabled: $eval env("ENABLE_LIDAR", true) name: laser body: base range: $eval param("/laser/max_range", 30) angle: min: $eval -param("/laser/fov", 3.14159) / 2 max: $eval param("/laser/fov", 3.14159) / 2 increment: $eval param("/laser/fov", 3.14159) / param("/laser/num_beams", 720) # Include external YAML files joints: $include joints.yaml # Include multiple items into a sequence models: - $[include] robots.yaml # Each YAML document becomes a list item ``` -------------------------------- ### Configure Model YAML to Use Plugin Source: https://github.com/avidbots/flatland/blob/master/docs/flatland_tutorials/create_plugin.md Add the Simple plugin configuration to the model YAML file to enable its use in the simulator. ```yaml - type: Simple name: simple ``` -------------------------------- ### Configure TricycleDrive Plugin Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/included_plugins/tricycle_drive.md This YAML configuration is used to set up the TricycleDrive plugin. It specifies required parameters like the plugin type, body name, and joint names, as well as optional parameters for odometry topics, noise, and covariance. ```yaml plugins: # required, specify TricycleDrive type to load the plugin - type: TricycleDrive # required, name of the plugin name: robot_drive # required, body of a model to set velocities and obtain odometry body: base # required, the front wheel joint front_wheel_joint: front_wheel_revolute # required, the rear left wheel joint rear_left_wheel_joint: rear_left_wheel_weld # required, the rear right wheel joint rear_right_wheel_joint: rear_right_wheel_weld # optional, defaults to odom, the name of the odom frame odom_frame_id: odom # optional, defaults to inf, rate to publish odometry at, in Hz pub_rate: inf # optional, defaults to "cmd_vel", the topic to subscribe for velocity # commands twist_sub: cmd_vel # optional, defaults to "odometry/filtered", the topic to advertise for # publish noisy odometry odom_pub: odometry/filtered # optional, defaults to "cmd_vel", the topic to advertise for publish # no noise ground truth odometry ground_truth_pub: odometry/ground_truth # optional, defaults to [0, 0, 0], corresponds to noise on [x, y, yaw], # the variances of gaussian noise to apply to the pose components of the # odometry message odom_pose_noise: [0, 0, 0] # optional, defaults to [0, 0, 0], corresponds to noise on # [x velocity, y velocity, yaw rate], the variances of gaussian noise to # apply to the twist components of the odometry message odom_twist_noise: [0, 0, 0] # optional, defaults to the diagonal [x, y, yaw] components replaced by # odom_pose_noise with all other values equals zero, must have length of 36, # represents a 6x6 covariance matrix for x, y, z, roll, pitch, yaw. # This does not involve in any of the noise calculation, it is simply # the output values of odometry pose covariance odom_pose_covariance: [0, 0, 0, 0, 0, 0 0, 0, 0, 0, 0, 0 0, 0, 0, 0, 0, 0 0, 0, 0, 0, 0, 0 0, 0, 0, 0, 0, 0 0, 0, 0, 0, 0, 0] # optional, defaults to the diagonal [x velocity, y velocity, yaw rate] # components replaced by odom_twist_noise with all other values equals zero, # must have length of 36, represents a 6x6 covariance matrix for rates x, # y, z, roll, pitch, yaw. This does not involve in any of the noise # calculation, it is simply the output values of odometry twist covariance odom_twist_covariance: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0] # optional, defaults to 0.0 which means no limit ``` -------------------------------- ### Configure Standard Laser Scanner Plugin Source: https://context7.com/avidbots/flatland/llms.txt Configure a standard forward-facing Laser plugin to simulate a 2D LIDAR. Specify topic, origin, range, angles, noise, and TF broadcasting. ```yaml plugins: # Standard forward-facing LIDAR - type: Laser name: front_laser body: base_link topic: scan # Publish sensor_msgs/LaserScan # Sensor placement origin: [0.2, 0, 0] # [x, y, yaw] offset from body # Scan parameters range: 30.0 # Maximum range (meters) angle: min: -2.356 # Start angle (rad, ~-135 deg) max: 2.356 # End angle (rad, ~135 deg) increment: 0.00436 # Angular resolution (rad) # Noise and rate noise_std_dev: 0.02 # Gaussian noise std dev (meters) update_rate: 40 # Publish rate Hz (inf = every step) # Layer filtering layers: ["all"] # Only detect objects in these layers # TF options broadcast_tf: true # Publish body -> laser TF frame: front_laser # TF frame ID # Performance options always_publish: false # Publish even without subscribers upside_down: false # Invert laser mounting orientation ``` -------------------------------- ### Configure CMakeLists.txt for Plugin Library Source: https://github.com/avidbots/flatland/blob/master/docs/core_functions/model_plugins.md Finds required packages and adds the plugin source file to be compiled as a library named 'my_plugins_lib'. ```cmake find_package(catkin REQUIRED COMPONENTS pluginlib flatland_server ) include_directories(include) add_library(my_plugins_lib src/const_velocity_plugin.cpp) ``` -------------------------------- ### YAML Preprocessor Source: https://context7.com/avidbots/flatland/llms.txt Information about Flatland's Lua-based YAML preprocessor for parametric model creation. ```APIDOC ## YAML Preprocessor Flatland includes a Lua-based YAML preprocessor for creating parametric models using environment variables and ROS parameters. ```yaml ``` -------------------------------- ### Configure Laser Plugin Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/included_plugins/laser.md Use this YAML configuration to set up a laser plugin. Specify the type, name, body attachment, range, and angle parameters. The 'topic' parameter defines the data publication topic, and 'origin' sets the laser's position and orientation relative to its attached body. ```yaml plugins: # required, specify Laser to load this plugin - type: Laser # required, name of the laser plugin, must be unique name: laser_back # optional, default to "scan", topic to publish the laser data topic: scan # required, name of the body to attach the laser to body: base_link # optional, default to [0, 0, 0], in the form of [x, y, yaw], the position # and orientation to place laser's coordinate system origin: [0, 0, 0] # optional, default to true, whether to publish TF broadcast_tf: true # optional, default to false, if true compute/publish even if no subscribers (for benchmarking) always_publish: false # optional, default to name of this plugin, the TF frame id to publish TF with # only used when broadcast_tf=true frame: laser_back # required, maximum range of the laser, minimum range assumed to be zero, in meters range: 20 # optional, default to 0.0, standard deviation of a gaussian noise noise_std_dev: 0 # required, w.r.t to the coordinate system, scan from min angle to max angle # at steps of specified increments # Scan direction defaults to counter-clockwise but clockwise rotations can be # simulated by providing a decrementing angle configuration. # e.g. min: 2, max: -2, increment: -0.1 (clockwise) angle: {min: -2.356194490192345, max: 2.356194490192345, increment: 0.004363323129985824} # optional, default to inf (as fast as possible), rate to publish laser scan messages update_rate: .inf # optional, default to ["all"], the layers to operate the laser at, # lasers only detects objects in the specified layers layers: ["all"] # optional, invert the mounting orientation of the lidar (default: false) # This will invert the laser's body->laser frame TF (roll=PI) # And sweep the lidar scan across a field mirrored across its mounted axis # (as if you physically mounted the lidar upside down) upside_down: false # another example - type: Laser name: laser_front body: base_link range: 30 angle: {min: -1.5707963267948966, max: 1.5707963267948966, increment: 1.5707963267948966} layers: ["layer_1", "layer_2", "layer_3"] update_rate: 100 noise_std_dev: 0.01 ``` -------------------------------- ### Visualize Laser Scan in RViz Source: https://context7.com/avidbots/flatland/llms.txt Launch RViz to visualize laser scan data. Add a LaserScan display and set the topic to '/scan'. ```bash # Visualize laser scan in RViz rosrun rviz rviz # Add LaserScan display, set topic to /scan # Check scan data rostopic echo /scan --noarr | head -20 ``` -------------------------------- ### Control Robot and Monitor Odometry via ROS Topics Source: https://context7.com/avidbots/flatland/llms.txt Use these bash commands to control robot movement by publishing Twist messages to the /cmd_vel topic and to monitor the robot's odometry output from filtered and ground truth topics. ```bash # Control the robot via command line rostopic pub /cmd_vel geometry_msgs/Twist "linear: x: 0.5 y: 0.0 z: 0.0 angular: x: 0.0 y: 0.0 z: 0.3" -r 10 # Monitor odometry output rostopic echo /odometry/filtered rostopic echo /odometry/ground_truth ``` -------------------------------- ### Configure Bool Sensor Plugin Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/included_plugins/bool_sensor.md Use this YAML configuration to set up the Bool Sensor plugin. Specify the plugin type, name, ROS topic, update rate, and the body to monitor for collisions. ```yaml plugins: # required, specify BoolSensor type to load the plugin - type: BoolSensor # required, name of the plugin, unique within the model name: MyBoolSensor # The ROS topic name to publish on ("/detector_out") # This will respect model namespaces # e.g. if this model has namespace "foo", it will publish on "/foo/detector_out" topic: detector_out # The update rate in hz update_rate: 10 # The model body to detect collisions on # Currently only supports collisions on a single body body: detector ``` -------------------------------- ### Configure Model YAML to Use Plugin Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/flatland_tutorials/create_plugin.md Enable the Simple plugin for a specific model by adding its type and name to the model's YAML configuration file. This tells Flatland which plugin to load for the model. ```yaml - type: Simple name: simple ``` -------------------------------- ### Launch Teleoperation Software Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/core_functions/joystick.md Run this command in a dedicated terminal to launch the teleoperation software. Press Ctrl-c to exit. ```none roslaunch teleop_twist_joy teleop.launch ``` -------------------------------- ### Export Plugin Configuration in package.xml Source: https://github.com/avidbots/flatland/blob/master/docs/core_functions/model_plugins.md Exports the plugin configuration by referencing the 'flatland_plugins.xml' file. This makes the plugins available to the Flatland server. ```xml ``` -------------------------------- ### Spawning Models Source: https://github.com/avidbots/flatland/blob/master/docs/core_functions/ros_services.md Dynamically spawn models into the simulation world after its instantiation. All input parameters are required. ```APIDOC ## POST /spawn_model ### Description Spawns a model into the simulation world using a provided YAML file and pose. ### Method POST ### Endpoint /spawn_model ### Parameters #### Request Body - **yaml_path** (string) - Required - Path to the model's YAML file. - **name** (string) - Required - Name of the model to spawn. - **ns** (string) - Required - Namespace for the model. Use an empty string for no namespace. - **pose** (geometry_msgs/Pose2D) - Required - The initial pose (position and orientation) of the model. ### Response #### Success Response (200) - **success** (bool) - True if the model was spawned successfully, false otherwise. - **message** (string) - An error message if the operation was unsuccessful. ``` -------------------------------- ### Spawning Models Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/core_functions/ros_services.md Dynamically spawn models into the simulation world after its instantiation. All input parameters are required. ```APIDOC ## POST /spawn_model ### Description Spawns a model into the simulation world using a provided YAML file and pose. ### Method POST ### Endpoint /spawn_model ### Parameters #### Request Body - **yaml_path** (string) - Required - Path to the model's YAML file. - **name** (string) - Required - The name to assign to the spawned model. - **ns** (string) - Required - The namespace for the model. Use an empty string for no namespace. - **pose** (geometry_msgs/Pose2D) - Required - The initial 2D pose (position and orientation) of the model. ### Response #### Success Response (200) - **success** (bool) - True if the model was spawned successfully, false otherwise. - **message** (string) - An error message if the operation was unsuccessful. ``` -------------------------------- ### Add Dependencies to package.xml Source: https://github.com/avidbots/flatland/blob/master/docs/core_functions/model_plugins.md Specifies the 'flatland_server' and 'pluginlib' packages as dependencies for the ROS package. ```xml flatland_server pluginlib ``` -------------------------------- ### Custom Constant Velocity Plugin for Flatland (Source) Source: https://context7.com/avidbots/flatland/llms.txt This C++ source file implements the `ConstVelocity` plugin. It parses configuration from YAML, retrieves the target body, and applies linear and angular velocities to the physics body before each simulation step. ```cpp // src/const_velocity_plugin.cpp #include #include #include #include namespace flatland_plugins { void ConstVelocity::OnInitialize(const YAML::Node &config) { flatland_server::YamlReader reader(config); vel_x = reader.Get("vel_x"); vel_y = reader.Get("vel_y"); omega = reader.Get("omega"); body = GetModel()->GetBody(reader.Get("body")); if (body == nullptr) { throw flatland_server::YAMLException("Body with given name does not exist"); } } void ConstVelocity::BeforePhysicsStep( const flatland_server::Timekeeper &timekeeper) { body->GetPhysicsBody()->SetLinearVelocity(b2Vec2(vel_x, vel_y)); body->GetPhysicsBody()->SetAngularVelocity(omega); } } // namespace flatland_plugins PLUGINLIB_EXPORT_CLASS(flatland_plugins::ConstVelocity, flatland_server::ModelPlugin) ``` -------------------------------- ### Register Simple Plugin in XML Source: https://github.com/avidbots/flatland/blob/master/docs/flatland_tutorials/create_plugin.md Register the Simple plugin with its type and base class in the plugin XML file. ```xml Simplest possible plugin to print hello world ``` -------------------------------- ### Initialize Node Handle with Model Namespace Source: https://github.com/avidbots/flatland/blob/master/docs/core_functions/model_plugins.md Initialize a ROS NodeHandle with the model's namespace to ensure correct topic scoping. ```cpp nh_ = ros::NodeHandle(model_->namespace_); ``` -------------------------------- ### Declare Plugins in flatland_plugins.xml Source: https://github.com/avidbots/flatland/blob/master/docs/core_functions/model_plugins.md Lists the exported plugins, specifying their type, base class, and a description. This file is used by flatland_server to discover available plugins. ```xml Constant velocity plugin ``` -------------------------------- ### Add Dummy World Plugin Test Source: https://github.com/avidbots/flatland/blob/master/flatland_server/CMakeLists.txt Adds a ROS test named dummy_world_plugin_test using Google Test. It links against flatland_lib and yaml-cpp. Ensure test/dummy_world_plugin_test.test and test/dummy_world_plugin_test.cpp exist. ```cmake add_rostest_gtest(dummy_world_plugin_test test/dummy_world_plugin_test.test test/dummy_world_plugin_test.cpp) target_link_libraries(dummy_world_plugin_test flatland_lib yaml-cpp) ``` -------------------------------- ### Flatland Plugin Header File Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/flatland_tutorials/create_plugin.md Define the Simple plugin class, inheriting from flatland_server::ModelPlugin. This header file declares the plugin's interface. ```cpp #include #ifndef FLATLAND_PLUGINS_SIMPLE_H #define FLATLAND_PLUGINS_SIMPLE_H using namespace flatland_server; namespace flatland_tutorials { class Simple : public ModelPlugin { public: void OnInitialize(const YAML::Node &config) override; }; }; #endif ``` -------------------------------- ### Flatland World Configuration Source: https://context7.com/avidbots/flatland/llms.txt Defines the simulation environment in YAML format. Includes physics properties, layers (static obstacles), and models (dynamic entities). Physics iterations and layer definitions are specified here. ```yaml # world.yaml - Complete world configuration example properties: velocity_iterations: 10 # Box2D velocity solver iterations (default: 10) position_iterations: 10 # Box2D position solver iterations (default: 10) layers: # Layer from ROS map_server format - name: "map" map: "conestogo_office.yaml" # Relative path to map yaml file color: [0.4, 0.4, 0.4, 1] # RGBA visualization color # Multiple layer names pointing to same physical layer (efficient aliasing) - name: ["obstacles", "walls", "boundaries"] map: "/absolute/path/layer.yaml" models: # Basic robot model - name: turtlebot1 namespace: "" # ROS namespace for topics/TF pose: [0, 0, 0] # Initial [x, y, yaw] position model: "turtlebot.model.yaml" # Path to model definition # Multiple robots with namespaces - name: turtlebot2 namespace: "robot2" pose: [5.0, 3.0, 1.57] model: "turtlebot.model.yaml" ``` -------------------------------- ### Verify Plugin Export with rospack Source: https://github.com/avidbots/flatland/blob/master/docs/core_functions/model_plugins.md Command to verify that the plugin XML file has been correctly exported and is discoverable by the ROS package system. ```bash $ rospack plugins --attrib=plugin flatland_server ``` -------------------------------- ### Configure Flatland to Use Custom Velocity Plugin Source: https://context7.com/avidbots/flatland/llms.txt This YAML configuration demonstrates how to use the custom `ConstVelocity` plugin within Flatland. It specifies the plugin type, assigns a name, links it to a body, and provides the necessary parameters for velocity and angular velocity. ```yaml # Using the custom plugin plugins: - type: ConstVelocity name: const_velocity_drive body: base vel_x: 1.0 vel_y: 0.2 omega: -0.5 ``` -------------------------------- ### Declare Plugin in XML Source: https://github.com/avidbots/flatland/blob/master/docs/doxygen/flatland_tutorials/create_plugin.md Register the Simple plugin with the plugin system by adding its declaration to the flatland_plugins.xml file. This makes the plugin discoverable by Flatland. ```xml Simplest possible plugin to print hello world ``` -------------------------------- ### Configure Tween Animation Plugin Source: https://context7.com/avidbots/flatland/llms.txt YAML configurations for the Tween plugin, demonstrating automatic sliding doors, trigger-controlled doors, and rotating platforms with various easing functions and modes. ```yaml plugins: # Automatic sliding door (yoyo mode) - type: Tween name: sliding_door body: door_body mode: yoyo # yoyo, once, loop, or trigger easing: cubicInOut # Easing function duration: 2.0 # Animation duration (seconds) delta: [2.0, 0, 0] # Movement [dx, dy, dtheta] # Trigger-controlled door - type: Tween name: triggered_door body: automatic_door mode: trigger trigger_topic: door_open # Subscribe std_msgs/Bool easing: quadraticOut duration: 1.5 delta: [0, 3.0, 0] # Slide sideways # Rotating platform (loop mode) - type: Tween name: rotating_platform body: platform mode: loop easing: linear duration: 10.0 delta: [0, 0, 6.283] # Full rotation # Available easing modes: # linear # quadraticIn, quadraticOut, quadraticInOut # cubicIn, cubicOut, cubicInOut # quarticIn, quarticOut, quarticInOut # quinticIn, quinticOut, quinticInOut # exponentialIn, exponentialOut, exponentialInOut # circularIn, circularOut, circularInOut # backIn, backOut, backInOut # elasticIn, elasticOut, elasticInOut # bounceIn, bounceOut, bounceInOut ``` -------------------------------- ### Configure IMU Plugin Source: https://context7.com/avidbots/flatland/llms.txt YAML configuration for the IMU plugin, specifying topics, TF frames, noise levels, and update rate. ```yaml plugins: - type: Imu name: imu_sensor body: base # Topic configuration imu_pub: imu/filtered # Noisy IMU data ground_truth_pub: imu/ground_truth # Noise-free IMU data enable_imu_pub: true # TF configuration imu_frame_id: imu broadcast_tf: true # Noise configuration (covariance diagonals) # Note: Only z-axis angular, x/y linear used in 2D orientation_noise: [0.0, 0.0, 0.001] # Roll, pitch, yaw noise angular_velocity_noise: [0.0, 0.0, 0.01] # Angular rate noise linear_acceleration_noise: [0.05, 0.05, 0.0] # Linear accel noise update_rate: 100 # Publish rate Hz ``` -------------------------------- ### Configure Tricycle Drive Plugin Source: https://context7.com/avidbots/flatland/llms.txt Configure the TricycleDrive plugin for robot kinematics with a steerable front wheel and fixed rear axle. Specify joint connections, topic names, frame IDs, and dynamic constraints. ```yaml plugins: - type: TricycleDrive name: tricycle_drive body: base # Required joint connections front_wheel_joint: front_wheel_revolute rear_left_wheel_joint: rear_left_wheel_weld rear_right_wheel_joint: rear_right_wheel_weld # Topic configuration twist_sub: cmd_vel # Twist.angular.z = front wheel angle odom_pub: odometry/filtered ground_truth_pub: odometry/ground_truth # Frame IDs odom_frame_id: odom ground_truth_frame_id: map pub_rate: 50 # Noise configuration odom_pose_noise: [0.01, 0.01, 0.005] odom_twist_noise: [0.02, 0.02, 0.01] # Steering constraints max_steer_angle: 0.785 # Max steering angle (rad, ~45 deg) # Dynamics constraints linear_dynamics: velocity_limit: 2.0 acceleration_limit: 1.5 deceleration_limit: 2.0 angular_dynamics: velocity_limit: 1.0 # Steering angular velocity limit acceleration_limit: 2.0 # Steering acceleration limit ```