A guide in how to configure the SWARM Platform

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.

ID
This section doesn't require an input! This will be set by the SWARM System for you and is an internal tracking tool.
RunLength
Valid Inputs:
30 to 99999 - Seconds
SimulationName
Valid Inputs:
Anything you like that is capable of being turned into a string.
Example:
Simulation-243
Scenario

Fields

Name
string
The Name of the Scenario
Options
Dictionary
The different ways to modify the scenario. Coming soon!

Valid Inputs

Name
Options
Environment

Valid Inputs

Name

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"
            }
        
StartingLevelName
The name of the level that you should start with. For example, in the SWARMHome environment, there are 3 levels: Home1, Home2 and Home3. If you want to start on Home2, you would put Home2 here and the system will automatically load that level.
            "Environment" {
                "Name": "SWARMHome",
                "StartingLevelName": "Home1"
            }
        
StreamVideo
A flag for turning on and off the "Live Streaming" feature, which allows you to view the output of the simulation in your browser. Turn this flag to "false" for maximum performance.
            "Environment" {
                "Name": "SWARMHome",
                "StartingLevelName": "Home1",
                "StreamVideo": true
            }
        
Options
The set of options that allows you to set the state of the environment when the level is loaded in Unreal Engine. Please see Environment Control for the available options.
            "Environment" {
                "Name": "SWARMHome",
                "StartingLevelName": "Home1",
                "StreamVideo": true,
                "Options": {
                    "Doors": "Open"
                }
            }
        
Data

Valid Inputs

Images
Provide a format field. Currently supported image types are PNG images.
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"
                }
            }
        
VehicleState
The state of the vehicle. Provides the logs in the SWARM format, which can be parsed with the SWARM Data Cruncher, available in February 2023.
            "Data" {
                "VehicleState": {
                    "Format": "SWARM"
                }
            }
        
Videos
A recorded video from the agents camera. Please note that this will change where you canset what data collect for each individual agent.
Please provide the name of the camera to record. This camera must exist on the vehicle.
            "Data" {
                "VehicleState": {
                    "Format": "MP4",
                    "VideoName": "TestVideo",
                    "CameraName": "Camera2"
                }
            }
        
Agents

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.

Vehicle
The type of Vehicle this agent is.
Available Options
Multirotor (Quadrotor UAV)
VehicleOptions
System wide options to set for the Agent.
Available Options
  • 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
Autopilot
Control system for the agent.
Available Options
SWARM
Sensors
What sensors to utilize. View detailed documentation on sensors here
Available Options
  • 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
                        }
                    }
                }
        
Example For LiDAR

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"
                        }
                    }
                }
        
Controller
The underlying position controller.
Available Options
SWARMBase

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
                }
            }
        
StartingPosition
The starting pose of the system.
Available Options
X, Y, Z, Yaw, Pitch, Roll (Required)

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
            }
        
Software Modules
The components of the SWARM Firmware to use.
Available Options
Please see SWARM Firmware API Documentation for more information.

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"
                    ]
                }
            }
        

Tags: