🔧 Configure your Environment¶

To configure your Environment and create new annotations for your robot to use, you can choose among the available interfaces, depending on your needs and the tools you are using.

How to configure your Environment with YAML Files¶

Probably the fastest and easiest way to create a new Environment and add new annotations is by using YAML files. This type of file provides a simple and human-readable overview of the Environment you are creating, its properties, and the relationships between the different elements.

To create a new Environment using YAML files, you can create a new file anywhere in the robot (a good choice is always the .pal folder).

touch ~/.pal/my_environment.yaml

Then, you can start configuring your Environment by editing the file you just created using any code editor.

vi ~/.pal/my_environment.yaml

The following is an example of a simple YAML file that creates a new Environment with a single Building called small_office which is composed of a single Floor and a single Map.

buildings:
  - name: small_office
    timezone: Europe/Madrid
    is_active: false
    is_enabled: true
    properties:
      []

building_anchors:
  - name: simple_building_anchor
    type: 0
    is_active: false
    is_enabled: true
    parent_key: small_office
    transform:
      translation:
        x: 0
        y: 0
        z: 0
      rotation:
        x: 0
        y: 0
        z: 0
        w: 1

floors:
  - name: small_office_floor
    level: 0
    is_active: false
    is_enabled: true
    parent_key: small_office
    anchor_key: small_office/simple_building_anchor
    transform:
      translation:
        x: 0
        y: 0
        z: 0
      rotation:
        x: 0
        y: 0
        z: 0
        w: 1


floor_anchors:
  - name: simple_floor_anchor
    type: 0
    is_active: false
    is_enabled: true
    parent_key: small_office/small_office_floor
    transform:
      translation:
        x: 0
        y: 0
        z: 0
      rotation:
        x: 0
        y: 0
        z: 0
        w: 1


waypoints:
  - name: waypoint_1
    is_active: false
    is_enabled: true
    parent_key: small_office/small_office_floor
    transform:
      translation:
        x: 4
        y: -4
        z: 0
      rotation:
        x: 0
        y: 0
        z: 0
        w: 1
  - name: waypoint_2
    is_active: false
    is_enabled: true
    parent_key: small_office/small_office_floor
    transform:
      translation:
        x: 4
        y: -11
        z: 0
      rotation:
        x: 0
        y: 0
        z: 0
        w: 1


waypoint_lists:
  - name: list_1
    is_active: false
    is_enabled: false
    parent_key: small_office/small_office_floor
    waypoint_keys:
      - small_office/small_office_floor/waypoint_1
      - small_office/small_office_floor/waypoint_2


lanes:
  - name: wall_1
    type: 1
    width: 0.25
    is_active: false
    is_enabled: true
    parent_key: small_office/small_office_floor
    vertexes:
      - transform:
          translation:
            x: -4.8399999999999999
            y: 2
            z: 0
          rotation:
            x: 0
            y: 0
            z: 0
            w: 1
      - transform:
          translation:
            x: 5
            y: 1.8
            z: 0
          rotation:
            x: 0
            y: 0
            z: 0
            w: 1
      - transform:
          translation:
            x: 4.7999999999999998
            y: -12.800000000000001
            z: 0
          rotation:
            x: 0
            y: 0
            z: 0
            w: 1
  - name: highway
    type: 2
    width: 0.25
    is_active: false
    is_enabled: true
    parent_key: small_office/small_office_floor
    vertexes:
      - transform:
          translation:
            x: -3
            y: 0
            z: 0
          rotation:
            x: 0
            y: 0
            z: 0
            w: 1
      - transform:
          translation:
            x: 1.5
            y: 0
            z: 0
          rotation:
            x: 0
            y: 0
            z: 0
            w: 1
      - transform:
          translation:
            x: 1.5
            y: -7
            z: 0
          rotation:
            x: 0
            y: 0
            z: 0
            w: 1


zones:
  - name: vo_table
    type: 1
    is_active: false
    is_enabled: true
    parent_key: small_office/small_office_floor
    vertexes:
      - transform:
          translation:
            x: 0
            y: -6
            z: 0
          rotation:
            x: 0
            y: 0
            z: 0
            w: 1
      - transform:
          translation:
            x: 0
            y: -11.5
            z: 0
          rotation:
            x: 0
            y: 0
            z: 0
            w: 1
      - transform:
          translation:
            x: -2
            y: -11.5
            z: 0
          rotation:
            x: 0
            y: 0
            z: 0
            w: 1
      - transform:
          translation:
            x: -2
            y: -6
            z: 0
          rotation:
            x: 0
            y: 0
            z: 0
            w: 1

maps:
  - name: small_office
    filename: /opt/pal/alum/share/pal_maps/maps/small_office/map.yaml
    frame_id: map
    is_active: false
    is_enabled: true
    type: 1
    namespace: ""
    parent_key: small_office/small_office_floor
    anchor_key: small_office/small_office_floor/simple_floor_anchor
    transform:
      translation:
        x: 0
        y: 0
        z: 0
      rotation:
        x: 0
        y: 0
        z: 0
        w: 1

Once you have created your Environment, you can start using it by loading its content into the Database. First, you need to make sure that the Advanced Navigation is stopped by using the command:

pal module stop advanced_navigation

Then, you can load the newly created Environment into the Database using the command:

ros2 run eulero_utils init_db_from_yaml /home/pal/.pal/my_environment.yaml

Attention

The argument of the init_db_from_yaml node must be the absolute path to your YAML configuration file.

After loading the Environment into the Database, you can start the Advanced Navigation again by using the command:

pal module start advanced_navigation

This will automatically load the new Environment and will start using all the Annotations that have been created.

The same way, you can also dump the current Environment into a YAML file by using the command:

ros2 run eulero_utils dump_db_to_yaml /home/pal/.pal/my_environment_backup.yaml

Attention

The argument of the dump_db_to_yaml node must be the absolute path to the destination YAML configuration file.

How to configure your Environment with ROS 2 Services¶

An alternative way of creating Environmental Annotations, especially useful for developers, is through ROS 2 Services. The list of all the available Services for creating and managing Environmental Annotations is available in the 🔌 Environmental Annotations API chapter.

For example, using this interface, to create the same small_office Environment, one can start by creating a new Building using the command:

ros2 service call /eulero_manager/create_building eulero_msgs/srv/CreateBuilding "new_building:
 name: 'small_office'
 timezone: 'Europe/Madrid'
 is_active: false
 is_enabled: true
 properties: []"

Then, to create a new BuildingAnchor inside this Building, one can use the command:

ros2 service call /eulero_manager/create_building_anchor eulero_msgs/srv/CreateAnchor "new_anchor:
  name: 'simple_building_anchor'
  transform:
    translation:
      x: 0.0
      y: 0.0
      z: 0.0
    rotation:
      x: 0.0
      y: 0.0
      z: 0.0
      w: 1.0
  is_active: false
  is_enabled: true
  parent_key: 'small_office'
  type: 0"

Attention

The parent_key argument must be the name of the Building you want to add the new BuildingAnchor to. This means that before creating a new BuildingAnchor, you must have created the Building it belongs to. Similarly, before creating a new Floor, you must have created the BuildingAnchor and the Building it belongs to.

And so on, you can continue creating any other Environmental Annotation using the corresponding ROS 2 Service.

How to configure your Environment with Rviz¶

Another, very useful and intuitive way of creating Environmental Annotations is through the RViz GUI. Using this GUI, you can create new Annotations such as Zones, Lanes, and Waypoints and add them to the corresponding Building and Floor.

Attention

When using RViz Interactive Markers to modify Environmental Annotations, remember to always set the Fixed Frame to the name of the current Building you are working on (The parent TF frame of all the others).

Considerations when configuring your Environment¶

When creating a new Environment or modifying an existing one, there are some considerations that you should take into account:

Keys: Each Environmental Annotation is identified by a unique key that is composed of the parent_key and the name of the Annotation itself. For example, let’s consider this sample Environment:
```
buildings:
  - name: sample_building
    # Other properties

floors:
  - name: sample_floor
    parent_key: sample_building
    # Other properties
```
In this example, the key of the Building is simply its name (sample_building) because it has no parents. Instead the key of the Floor is composed of the parent_key and the name of the Floor itself (sample_building/sample_floor).

This information is useful because if you want to create a new Waypoint on the sample_floor, you need to specify the parent_key as sample_building/sample_floor.
```
waypoints:
  - name: waypoint_1
    parent_key: sample_building/sample_floor
    # Other properties
```
Activate VS Enable: Any Environmental Annotation comes with two state variables indicating its current status (Active, Inactive) and its desired status (Enabled, Disabled). The current status indicates whether the Annotation is currently loaded and being used by the Navigation. The desired status, instead, indicates whether a certain Annotation should be automatically activated once its parent is activated. For example, let’s consider this sample Environment:
```
floors:
  - name: first_floor
    is_active: true
    is_enabled: true
    # Other properties
  - name: second_floor
    is_active: false
    is_enabled: false
    # Other properties

waypoints:
  - name: waypoint_1
    is_active: false
    is_enabled: true
    parent_key: some_building/second_floor
    # Other properties

  - name: waypoint_2
    is_active: false
    is_enabled: true
    parent_key: some_building/second_floor
    # Other properties
```
In this example, the waypoint_1 and the waypoint_2 are both Enabled but not Active. This is because their parent, the Floor named second_floor is Inactive. Having the waypoint_1 and the waypoint_2 set to Enabled means that they will be automatically activated once their parent, the Floor called second_floor is activated.
Activation and Enabling are Propagated: When changing the current status or the desired status of any Environmental Annotation, the change is propagated to all the children of the Annotation. This means that if you Activate a Floor, all the Waypoints, Zones, Lanes, etc. that are Enabled will be activated as well. Similarly, if you Deactivate, Enable or Disable any Annotation, the change will be propagated to all children.
Activation and Enabling Limitations: When changing the current status or the desired status of any Environmental Annotation, there are a few limitations that you should take into account:
- Only one Building can be Active at a time.
- Only one Floor can be Active at a time.
- As Enabled Buildings will eventually become Active, only one Building can be Enabled at a time.
- As Enabled Floors will eventually become Active, only one Floor can be Enabled at a time.
Anchors: This Environmental Annotation is in charge of connecting different Floors in the same Building and different Maps in the same Floor. An Anchor is simply a point in the Environment that is common to different Floors or to different Maps. For example, an Anchor that connects different Floors in the same Building could be the elevator or the stairs. Similarly, an Anchor that connects different Maps in the same Floor could be a door, a column or the docking station of the robot. In general, an Anchor doesn’t need to be representative of a physical object, but it is simply a reference that we use to connect multiple Environmental Annotations.