The SWARM Configuration is designed to be as simple and easy to use as possible. Here you will find a detailed guide on the settings and available parameters for each and every parameter in the settings files, along with detailed instructions in how to set up said files to easily execute complex simulation setups with ease.
Example Configuration File
Let's start off with an example. Below you will see a JSON document that you can also view in `settings` from the root of the project.
{
"ID": 0,
"SimulationName": "example",
"RunLength": 55.0,
"Scenario": {
"Name": "DataCollection",
"Options": {
"MultiLevel": false,
"LevelNames": [
"Home1"
]
}
},
"Environment": {
"Name": "SWARMHome",
"StartingLevelName": "Home1",
"StreamVideo": true,
"Options": {
"Doors": "Open",
"Lights": "On",
"FurnitureRandomization": "On"
}
},
"Data": {
"VehicleState": {
"Format": "SWARM"
},
"Video": {
"Format": "MP4",
"VideoName": "TestVideo"
}
},
"Agents": {
"Drone1": {
"Vehicle": "Multirotor",
"VehicleOptions": {
"UseLocalPX4": true,
"RunROSNode": true,
"PlanningCoordinateSystem": "NED"
},
"AutoPilot": "SWARM",
"Sensors": {
"LiDAR": {
"LidarSensor1": {
"Hardware": "VelodynePuck",
"Method": "Colosseum",
"Enabled": true,
"X": 0.35,
"Y": 0.0,
"Z": 0.0,
"Roll": 0.0,
"Pitch": 0.0,
"Yaw": 0.0,
"PublishingRate": 20.0,
"Settings": {
}
}
},
"Barometers": {
"Barometer": {
"Enabled": true,
"Method": "Colosseum",
"PublishingRate": 5.0
}
},
"IMU": {
"Imu1": {
"Enabled": true,
"Method": "Colosseum",
"PublishingRate": 100.0
}
},
"GPS": {
"Gps1": {
"Enabled": true,
"Method": "Colosseum",
"PublishingRate": 10.0
}
},
"Magnetometers": {
"Magnetometer": {
"Enabled": true,
"Method": "Colosseum",
"PublishingRate": 10.0
}
},
"Odometers": {
"Odometer1": {
"Enabled": true,
"Method": "Colosseum",
"PublishingRate": 25.0
}
},
"Distance": {
"Distance1": {
"Hardware": "Velodyne",
"Method": "Colosseum",
"Enabled": true,
"X": 0.35,
"Y": 0.0,
"Z": 0.0,
"Roll": 0.0,
"Pitch": 0.0,
"Yaw": 0.0,
"Settings": {
"MaxRange": 40.0
}
}
},
"Cameras": {
"Camera1": {
"Enabled": true,
"X": 0.35,
"Y": 0.0,
"Z": 0.0,
"Roll": 0.0,
"Pitch": 0.0,
"Yaw": 0.0,
"Settings": {
"ImageType": "Scene",
"Width": 640,
"Height": 480,
"FOV_Degrees": 90.0,
"FramesPerSecond": 24.0
}
}
}
},
"Controller": {
"Name": "SWARMBase",
"Gains": {
"P": 0.95,
"I": 0.02,
"D": 0.05
}
},
"StartingPosition": {
"X": 0.0,
"Y": 0.0,
"Z": -1.0,
"Roll": 0.0,
"Pitch": 0.0,
"Yaw": 0.0
},
"SoftwareModules": {
"HighLevelBehavior": {
"Algorithm": {
"Level": 1,
"States": [],
"Parameters": {
"completed_waypoint_distance": 1.5
},
"InputArgs": [
"Trajectory"
],
"ClassName": "PathFollowing",
"ReturnValues": [
"Position",
"Heading",
"Speed"
]
},
"Publishes": [
"MovementCommand"
],
"Subscribes": [
"AgentState"
]
},
"LowLevelPathPlanning": {
"Algorithm": {
"Level": 1,
"States": [],
"Parameters": {},
"InputArgs": [
"MovementCommand"
],
"ClassName": "PassThroughPlanner",
"ReturnValues": [
"MovementCommand"
]
},
"Parameters": {},
"Publishes": [],
"Subscribes": [
"MovementCommand",
"AgentState"
]
}
}
}
}
}
Example Dissection
Let's disect this example document by module.
ID
This ID is a unique number that is correlated to the SWARM system. Don't worry, this is autogenerated and you don't need to keep count.
RunLength
This is the number of seconds that the simulation is allotted to run. We use this as a circuit breaker in case there are any problems when code runs.
SimulationName
This is a unique name for your simulation, which you can create or can be created for you using Unique Identifiers.
Scenario
This is where you can manage the high-level components of the simulation. For right now, data collection is a bit of a freeplay where the simulation will track the location of the Agent and complete the simulation once the agent has completed all trajectory points.
Environment
This section is very important. Here, you are provided with the name of the environment. This name is queried from the SWARM Core system through the "List Environments" section. You can also set whether you wish to view output or not.
Data
This is where you can define what data you would like to collect throughout the simulation. Please see "Collecting Data" to learn more.
Agents
This is where your agents live. Here, you define all aspects of the system, to include the sensors available, what autopilot to run and what software should be running onboard. Think of this as your one stop shop for adding capabilities to the UAV running onboard.
What Can You Put Here?
This section describes what the possible inputs are for each section that is listed in the document. Please refer to this section frequently, as additions will be added regularly.
Fields
Valid Inputs
Valid Inputs
The Name of the Environment. This is a very specific name that should be copied exactly. Please find the list of available environments here: Supported Environments.
Please note the lack of a space in the name. This is important for the system to operate effectively!
"Environment" {
"Name": "SWARMHome"
}
"Environment" {
"Name": "SWARMHome",
"StartingLevelName": "Home1"
}
"Environment" {
"Name": "SWARMHome",
"StartingLevelName": "Home1",
"StreamVideo": true
}
"Environment" {
"Name": "SWARMHome",
"StartingLevelName": "Home1",
"StreamVideo": true,
"Options": {
"Doors": "Open"
}
}
Valid Inputs
Provide the number of images to take per second.
Provide the name of the Camera to use. This camera must be specified in the "Sensors" section for one of the agents.
"Data" {
"Images": {
"Format": "PNG",
"ImagesPerSecond" 5,
"CameraName": "Camera2"
}
}
"Data" {
"VehicleState": {
"Format": "SWARM"
}
}
Please provide the name of the camera to record. This camera must exist on the vehicle.
"Data" {
"VehicleState": {
"Format": "MP4",
"VideoName": "TestVideo",
"CameraName": "Camera2"
}
}
Description
This is the space to configure your set of agents. Each Agent must have a unique name. A general scheme we use is to label agents as Drone1, Drone2, etc.
- UseROSNode - A Boolean flag that will run the ROS node of your choice
- UseLocalPX4 - A Boolean flag that will run a local (not in SWARM) version of PX4
- PlanningCoordinateFrame - The coordinate frame to publish ROS information in
- Cameras
- LiDAR
- Barometer
- Magnetometer
- Distance Sensor
- IMU
- GPS
- AirSpeed (Coming Soon)
Example For Cameras
The below example creates a single camera located 350 centimeters from the center point of the agent (front) in the North, East, Down coordinate frame. This camera is set up to record 720p video or images, depending on the data type.
"Cameras": {
"Camera1": {
"X": 0.35,
"Y": 0.0,
"Z": 0.0,
"Roll": 0.0,
"Pitch": 0.0,
"Yaw": 0.0,
"Settings": {
"ImageType": "Scene",
"Width": 1280,
"Height": 720,
"FOV_Degrees": 90.0,
"FramesPerSecond": 24.0
}
}
}
The below example sets up a LiDAR Sensor that publishes a Point Cloud at 20 Hz. If using ROS, this publishes a sensor_msgs/PointCloud2. The Hardware tag supports developing specific hardware sensor profiles that are capable of acting as plug and play modules for your specific hardware.
"LiDAR": {
"LidarSensor1": {
"Enabled": true,
"Hardware": "VelodynePuck",
"Method": "Colosseum",
"X": 0.35,
"Y": 0.0,
"Z": 0.0,
"Roll": 0.0,
"Pitch": 0.0,
"Yaw": 0.0,
"PublishingRate": 20.0,
"Settings": {
"NumberOfChannels": 16,
"RotationsPerSecond": 10,
"PointsPerSecond": 100000,
"VerticalFOVUpper": -15,
"VerticalFOVLower": -25,
"HorizontalFOVStart": -20,
"HorizontalFOVEnd": 20,
"DataFrame": "SensorLocalFrame"
}
}
}
Example
The below example would be the standard set of PID gains used. Tune to your liking!
"Controller": {
"Name": "SWARMBase",
"Gains": {
"P": 0.97,
"I": 0.1,
"D": 0.15
}
}
Example
The below example would be the standard set of PID gains used. Tune to your liking!
"StartingPosition": {
"X": 0.0,
"Y": 0.0,
"Z": -1.0,
"Roll": 0.0,
"Pitch": 0.0,
"Yaw": 0.0
}
Example
The below example setups up an agent that can follow a set of waypoints loaded through the Trajectory file, while recording either video or images, depending on what you choose.
Please note that a LowLevelPathPlanning module is always reqiured!
"SoftwareModules": {
"HighLevelBehavior": {
"Algorithm": {
"Level": 1,
"States": [],
"Parameters": {
"completed_waypoint_distance": 1.5
},
"InputArgs": [
"Trajectory"
],
"ClassName": "PathFollowing",
"ReturnValues": [
"Position",
"Heading",
"Speed"
]
},
"Publishes": [
"MovementCommand"
],
"Subscribes": [
"AgentState"
]
},
"LowLevelPathPlanning": {
"Algorithm": {
"Level": 1,
"States": [],
"Parameters": {},
"InputArgs": [
"MovementCommand"
],
"ClassName": "PassThroughPlanner",
"ReturnValues": [
"MovementCommand"
]
},
"Parameters": {},
"Publishes": [],
"Subscribes": [
"MovementCommand",
"AgentState"
]
}
}