Adding custom definitions

Phobos' definition folder

Phobos aims to be extendable. This is achieved by parsing different definition files when starting up Phobos, which get then included into the internal hierarchy of Phobos. Therefore, you can create your own custom definitions for motors, sensors etc. using yaml. Simply add an entry to the corresponding file.

To add a new definition, create a yaml file (or extend an existing one) in the Phobos configuration folder. By default these reside in ~/.config/phobos/definitions for Linux, ~/Library/Application Support/phobos for Mac Darwin and in ~/AppData/Roaming/phobos for Windows.

The name of the file does not matter, but note, that the already existing files (defaultMotors.yml etc.) will be overwritten when updating Phobos, so make sure you keep your changes save.

You are free to add any custom parameter into the definitions you like. However, the information is then parsed according to the related parser and used if the simulation engine is able to interpret the values. This means, that the specific parameter will not be exported to SDF, unless the SDF parser is changed.

The generic SMURF file format will contain all the general parameters of the definition, which makes it a great format to implement custom solutions without need to adjust the parser.

Custom parameters, that are placed inside a category (such as the sdf or mars category) in the sensor definitions will be saved in an annotation object attached to the actual sensor, motor or controller. That way, different export configurations can be created more easily and the additional information is separated from the simple object.

Motor definitions

An example of a motor definition file can be seen here:

motors:
    # Example motors
    motor_name:                       # Name of the motor within phobos
        general:                      # General parameters of the motor
            type: super_motor         # Internal motor type, maybe used for simulator
            shape: resource://dc      # Graphical representation in Phobos
            size: 0.2                 # Size of the graphical representation in Phobos
            categories:               # Category in which the motor will be listed
                - generic
        controller: super_controller  # Controller used for this controller
        maxSpeed: 3.141               # Default value for the max speed
        maxEffort: 50.0               # Default value for the max effort
        CustomParameter: Foo          # Bar

Controller definitions

An example of a controller definition can be seen here:

controllers:
    # generic controllers
    pid:                              # Name of the controller within Phobos
        general:                      # General information for phobos
            type: PID                 # Controller type
            shape: resource://pid     # Graphical representation in Phobos
            size: 0.2                 # Size of the graphical representation in Phobos
            categories:               # Categories in which the controller will be listed
                - generic
                - motor
        p: 20.0                       # Parameters of the PID
        i: 1.0
        d: 0.1

Sensor definitions

An example of a sensor definition can be seen here:

sensors:
    Ray_sensor:                         # Name
        general:                        # General parameters of the sensor
            type: ray_sensor            # Sensor type, maybe used for simulator
            shape: resource://ray       # Graphical representation
            size: 0.2                   # Size of the graphical representation
            categories:                 # Categories of the sensor
                - scanning
                - SDF
        width: 144                      # Generic parameter follow this line
        height: 1
        opening_width: &0.5*math.pi&    # Math parsing for special values in & symbols
        opening_height: &0.5*math.pi&
        max_distance: 100
        min_distance: 0
        mars:                           # Special parameters used for exporting to smurf / mars:
            type: RaySensor             # these will be put in an annotation object attached to the sensor
        sdf:                            # Special parameters used for SDF export
            type: ray
            scan:
                horizontal:
                    samples: 1
                    resolution: 1
                    min_angle: 0.
                    max_angle: 0.
                vertical:
                    samples: 1
                    resolution: 1
                    min_angle: 0.
                    max_angle: 0.