obstacle distance msg update

[mrivi]

update distances description according to latest obstacle_distance mavlink message

[mhkabir]

What does "local" north mean here?

[ChristophTobler]

It means North of the local coordinate system -> not necessarily global North (depending on the estimation)

[mrivi]

@dagar can we merge this? It's only an update of the comment

[MaEtUgR]

Merging because it directly reflects the MAVLink message definition of the data that gets read into this uORB message, see : https://mavlink.io/en/messages/common.html#OBSTACLE_DISTANCE

distances: Distance of obstacles around the UAV with index 0 corresponding to local North. A value of 0 means that the obstacle is right in front of the sensor. A value of max_distance +1 means no obstacle is present. A value of UINT16_MAX for unknown/not used. In a array element, one unit corresponds to 1cm.

@mhkabir This definition makes sense especially for any obstacle distance information based on some kind of memory like a map which should not rotate with the vehicle. A body based representation would only be favourable if it's used for a "stupid" sensor that doesn't have a memory and doesn't need the vehicle orientation just knows what it sees in that moment from the sensor orientation frame. If that's what we want is up to discussion and in the case we want to change something likely also the MAVLink message needs to change.

[mhkabir]

@MaEtUgR Then the message definition should be updated to not mention "sensor" anywhere, if you're using this as a generic way to transport a simplified "map" representation.

In it's current form it is not intuitive.

[hamishwillee]

@mhkabir @MaEtUgR

Then the message definition should be updated to not mention "sensor" anywhere, if you're using this as a generic way to transport a simplified "map" representation.

Not possible because the message additionally includes fields with sensors in the name (changing would be compatibility break) and may either transport info from a sensor system or from a map.

It could be improved though. Below is a better description.

    <message id="330" name="OBSTACLE_DISTANCE">
      <description>Obstacle distances around the system, starting from North in increment degrees clockwise.</description>
      <field type="uint64_t" name="time_usec" units="us">Timestamp (UNIX Epoch time or time since system boot). The receiving end can infer timestamp format (since 1.1.1970 or since system boot) by checking for the magnitude the number.</field>
      <field type="uint8_t" name="sensor_type" enum="MAV_DISTANCE_SENSOR">Class id of the distance sensor type.</field>
      <field type="uint16_t[72]" name="distances" units="cm">Distance of obstacles around the UAV with index 0 corresponding to local North. A value of 0 means that the obstacle is right in front of the sensor. A value of max_distance +1 means no obstacle is present. A value of UINT16_MAX for unknown/not used. In a array element, one unit corresponds to 1cm.</field>
      <field type="uint8_t" name="increment" units="deg">Angular width in degrees of each array element.</field>
      <field type="uint16_t" name="min_distance" units="cm">Minimum distance the sensor can measure.</field>
      <field type="uint16_t" name="max_distance" units="cm">Maximum distance the sensor can measure.</field>
    </message>

For max_distance we might change "max distance" to: maximum distance for reliable data.