NMS Navigation Data Grabber

How to use the NMS Navigation Data Grabber robot skill

Query data from the NMS (Navigation Messaging System). This skill subscribes to the Navigation2D scan stream and exposes Control Commands that return distance values from the most recent scan, allowing other robot skills (or scripts) to query range data at specific angles.

How It Works

The skill listens for scan updates broadcast by any navigation/lidar skill that publishes to the Navigation Messaging System (Navigation2DV1). Each scan is a set of ScanPoint records containing:

• Degree - the angle (0-359) where a point was sampled
• Distance - distance in centimeters to the detected object (0 means nothing detected)
• Confidence - detection confidence (0 = none, 255 = high)

The most recent scan is held in memory and queried on demand by the Control Commands listed below. The title bar counter shows how many scans have been received since the project loaded.

Requirements

A navigation/lidar skill that publishes to the NMS Navigation2D stream must be loaded in the same project (e.g. an RPLidar, YDLidar, or other 2D scanner skill). Without an active publisher, no scan data will arrive and Control Commands will throw "No scan data has been received yet."

Control Command Examples

All commands return a float distance in centimeters. Degrees are normalized to [0, 360) - negative values and values 360 wrap automatically.

GetRangeAtDegree

Returns the distance at the scan point closest to the requested degree.

Parameters:

• Degree (number, 0-359) - angle to query

Returns: distance in cm at that angle (or 0 if nothing detected at the closest point)

Example (JavaScript):

var distance = controlCommand("NMS Navigation Data Grabber", "GetRangeAtDegree", 0);
print("Distance straight ahead: " + distance + " cm");

GetHighestRangeBetweenDegrees

Scans all points within an ARC and returns the largest distance found. Useful for finding the most open direction within a range.

Parameters:

• From Degree (number, 0-359) - start of arc
• To Degree (number, 0-359) - end of arc

The ARC is walked clockwise from From to To. If From > To, the ARC wraps past 360 (e.g. From=350, To=10 covers a 20 ARC across the front).

Returns: highest distance in cm within the arc, or 0 if no points are in range.

Example (JavaScript):

// find the most open angle in the front 60 arc
var maxDist = controlCommand("NMS Navigation Data Grabber", "GetHighestRangeBetweenDegrees", 330, 30);

GetLowestRangeBetweenDegrees

Scans all points within an ARC and returns the smallest non-zero distance. Points with Distance == 0 (no detection) are skipped, since zero would otherwise always win.

Parameters:

• From Degree (number, 0-359) - start of arc
• To Degree (number, 0-359) - end of arc

Same wrap-around behavior as GetHighestRangeBetweenDegrees.

Returns: lowest non-zero distance in cm within the arc, or 0 if no detections.

Example (JavaScript) - obstacle check:

// closest object in front 60 arc
var closest = controlCommand("NMS Navigation Data Grabber", "GetLowestRangeBetweenDegrees", 330, 30);

if (closest > 0 && closest < 50)
  print("Obstacle ahead at " + closest + " cm - stop!");

Notes

• Data freshness - commands always operate on the most recent scan. If your publisher updates at 10 Hz, queries will reflect data up to ~100 ms old.
• Coordinate convention - 0 is the robot's forward direction. Angles increase clockwise (right side = 90, rear = 180, left side = 270). This matches the convention used by the rest of the NMS stack.
• No detection vs. close range - GetLowestRangeBetweenDegrees deliberately ignores 0 values. If you need to know whether any point was returned, use GetHighestRangeBetweenDegrees first or query specific angles individually.

Errors

Control Commands for the NMS Navigation Data Grabber robot skill

There are Control Commands available for this robot skill which allows the skill to be controlled programmatically from scripts or other robot skills. These commands enable you to automate actions, respond to sensor inputs, and integrate the robot skill with other systems or custom interfaces. If you're new to the concept of Control Commands, we have a comprehensive manual available here that explains how to use them, provides examples to get you started and make the most of this powerful feature.

GetRangeAtDegree

Get the range value at the specified degree (0-359)

• Parameter 3: Degree as Number (required)
• Returns: Float [1.5e45 to 3.4e38]

Example:

controlCommand("NMS Navigation Data Grabber", "GetRangeAtDegree", Degree as a number)

GetHighestRangeBetweenDegrees

Get the highest range value between the specified degrees (0-359)

• Parameter 3: From Degree as Number (required)
• Parameter 4: To Degree as Number (required)
• Returns: Float [1.5e45 to 3.4e38]

Example:

controlCommand("NMS Navigation Data Grabber", "GetHighestRangeBetweenDegrees", From Degree as a number, To Degree as a number)

GetLowestRangeBetweenDegrees

Get the lowest range value between the specified degrees (0-359)

• Parameter 3: From Degree as Number (required)
• Parameter 4: To Degree as Number (required)
• Returns: Float [1.5e45 to 3.4e38]

Example:

controlCommand("NMS Navigation Data Grabber", "GetLowestRangeBetweenDegrees", From Degree as a number, To Degree as a number)