RapidSense API

States

RapidSense is comprised of 4 states: discovery, calibrating, operating, and fatal. The transitions are coordinated by users of the system based on what commands they issue to RapidSense. If at any point an error is encountered that requires user-intervention to resolve, RapidSense transitions into a fatal state and will not operate until the cause is resolved. The following figure illustrates the transitions.

Messages

The following messages define the RapidSense 2.x API.

For REST interface endpoints, use port number 11235. For example, http://localhost:11235/volumes.

Volumes

General description

Users can create, read, update, and delete volumes defined in the project. This is a purely REST interface.

Endpoint	`/volumes`
Supported Operations	GET, POST, PUT, and DELETE
Base Endpoint	`<hostname>:<port>/volumes`

Create

To create a volume, users POST to the /volumes endpoint.

Operation	POST
Description	Creates a volume.
Request	`POST <hostname>:<port>/volumes`
Response Body Format
Example Response Body

Read

To read a list of all volumes configured in RapidSense, users can perform a GET on the /volumes endpoint and receive a list of all volumes with their IDs and bounds.

Operation	GET
Description	Returns a list of all configured volumes in the system.
Request
Response Body Format
Example Response Body

Update

To update a volume, users PUT to the /volumes/<id> endpoint providing the volume ID. The volume ID must exist already otherwise, the request errors out with a bad request error code. Updates must be idempotent, i.e., updates must be a full replacement of the volume details.

Operation	PUT
Description	Updates a volume or creates a new volume if the ID does not match any existing volume IDs.
Request
Request Body Format
Response Body Format
Example Request Body
Example Response Body

Delete

To remove / delete a volume, users DELETE on the /volumes/<id> endpoint providing the ID to remove.

Operation	DELETE
Description	Removes a volume.
Request
Request Body Format	None.
Response Body Format	None.

Status

Users of the system can query the status of RapidSense either via the ASCII interface through the GetRapidSenseStatus command or via the REST interface through the /status endpoint.

ASCII Message Definition

Structure
Argument Description	N/A
Function Description	This command can be called as soon as the RTR controller accepts a socket. It returns the latest status of RapidSense. All returned values are strings.
Response Details	The response details contains a list of rapid sense state and error codes. The format is “GetRapidSenseStatus,<version>,<state>,<num-sensors><sensor-status><num-errors>,<list-of-error-codes>” Parameter descriptions: RapidSense Version major.minor.build RapidSense State IDLE (0), CALIBRATING (1), OPERATING (2), FATAL (3) Sensor Status(es) A mapping of sensor serial number to an integer representing the sensor state. UNKNOWN(0), DISCONNECTED(1), UNCALIBRATED(2), CALIBRATED(3) Active RapidSense Error Code(s) A list of actives errors in form of error codes: 5xxx (any integer in the range 5000-5999 is a RapidSense error code, NOTE: not all are used!) Refer to table 1 below for recovery strategies.
Example CSV Request
Example YAML Response
Example CSV Responses

REST Endpoint & JSON Message Definition

Endpoint
Operation	GET
Description	Returns the status of RapidSense.
Response Body Format
Example Request Body
Example Response Body

Scan Scene

Users can scan the scene using 4 modes: snapshot, streaming, off, and clear. These operations affect the motion planning, enabling dynamic collision avoidance.

ASCII Message Definition

Structure
CSV Arguments + Description	The mode by which to scan the scene: Start streaming = 1 Stop streaming = 2 Clear = 3
YAML Arguments + Description	Start streaming = “start_streaming” Stop streaming = “stop_streaming” Clear = “clear”
Function Description	This command changes the scanning mode for RapidSense.
Response Details	Whether the system is set to the requested mode.
Example CSV Request
Example CSV Response
Example YAML Request
Example YAML Response

Calibration Setup

Users can setup RapidSense for calibration through the sensors and markers interfaces.

Markers

Markers are persisted between usages of RapidSense. Users can create, read, update, and delete markers for the system. Not all requests require the {id}field. The marker ID is the resource ID, as far as REST semantics is concerned.

Endpoint
Supported Operations	GET, PUT, POST, PATCH, DELETE
Base Endpoint

Read

To receive a list of all markers configured for RapidSense, users can perform a GET on the /markers endpoint and receive a list of all marker information. To receive a specific marker, users can perform a GET providing the marker’s ID in the {id} field.

Operation	GET
Description	Returns a list of all markers in the system.
Request
Response Body Format
Example Response Body
HTTP Code Responses	N/A - returns an empty list if no markers exist.

Operation	GET
Description	Returns a single marker by its ID.
Request
Response Body Format
Example Response Body
HTTP Code Responses	`404` If no marker exists for that ID.

Create, Update, or Delete

The above data format can also be used to create new markers, update existing markers, or delete markers from the system.

Operation	POST
Description	Create a single marker.
Request
Request Body Format
Example Response Body
HTTP Code Responses	`422 Unprocessable Content` - One or more markers with the provided IDs already exists, the ID is outside the range of the `36h11` tag family, or the length is outside the acceptable range. `200 OK` - Response accepted

Sensors

The sensors endpoint is automatically populated with detected sensors. Any sensors that are not configured meaning not setup for calibration, return default values regarding their calibration setup. The following table details the general REST endpoint information needed to setup calibration for a sensor.

Endpoint
Supported Operations	GET and PATCH
Base Endpoint

Read

To read a list of all sensor configurations for RapidSense, users can perform a GET on the /sensors endpoint and receive a list of all sensor information including the resource’s ID. Additionally, users can perform a GET on a single sensor using the sensor’s resource ID.

Operation	GET
Description	Returns a list of all detected sensors in the system.
Request
Response Body Format
Example Response Body

Update

To update a sensor’s calibration setup information, users can perform a PATCH on /sensors/<id>. Users associate a marker to a sensor. If a stationary marker is not being used or set, users do not provide that object.

Operation	PATCH
Description	Updates a sensor’s calibration parameters.
Request
Request Body Format
Example Request Body
Example Response Body

Calibrating

A user of the system (e.g., a script) can move the robot with a calibration standard to a certain location and initiate the calibration of a sensor, then move onto the next sensor until complete. The calibration process is coordinated by the calibration service. The API can be found at https://realtimerobotics.atlassian.net/wiki/spaces/RS/pages/2900951220 .

Height Check (formerly Query Clearance)

General description

An area within a volume can be queried for its maximum height. This can be used for querying a placement location for a package on a pallet, as an example. The caller in this case would compute the difference in the height of the expected landing spot for that package and the actual landing spot returned by height check and adjust the place location height. For a more detailed treatment of the design and purpose please see here.

Users can create, read, update, and delete height check filter objects and adjust their parameters. Creation of filter objects and adjusting the filter parameters can only be performed via the REST interface. To query the filter for heights, users have the option of using the ASCII interface or the REST interface.

Endpoint
Supported Operations	GET, PATCH, POST, PUT, and DELETE
Base Endpoint

Create

To create an instance of the height check filter, users must POST on the /heights endpoint, providing the volume ID within the request body.

Operation	POST
Description	Creates a volume.
Request
Request Body Format
Response Body Format
Example Response Body

Read

To read a list of all height filters configured in RapidSense, users can perform a GET on the /heights endpoint and receive a list of all volumes with their IDs and bounds.

Operation	GET
Description	Returns a list of all configured volumes in the system.
Request
Response Body Format
Example Response Body

Update

To update a filter’s parameter(s), users can perform a PUT on /heights/<id>.

Operation	PUT
Description	Updates a height filter’s parameters.
Request
Request Body Format
Response Body Format
Example Request Body
Example Response Body

Delete

To remove / delete a height filter, users DELETE on the /heights/<id> endpoint providing the ID to remove.

Operation	DELETE
Description	Removes a height filter.
Request
Request Body Format	None.
Response Body Format	None.

To query heights

Users can query the maximum height of a specified area via the ASCII interface or the REST interface. Users specify the centroid (the x / y center point) along with the length (distance along the x-axis) and width (distance along the y-axis) of the area to query for height. The maximum height in that specified area is returned in units of meters. Below are details regarding both the ASCII and REST interfaces.

ASCII Message Definition

Structure
Argument Description	id: the ID of the filter instance (returned when a user POSTs on `/heights`. centroid: the center of the area as an x, y position relative to the volume’s origin (lowest x and y values). width: the width of the area (along the x-axis). length: the height of the area (along the y-axis). NOTE: Units are set by `SetUnits`.
Function Description	Height check uses the heuristic of maximum value within the specified area within the volume. NOTE: objects that are to be placed with significant overhang will bias the measurements so care should be taken in computing this value to allow overhangs but not bias the calculations to negatively impact system operations. This command can be run at any time while RapidSense is in OPERATING state.
Response Details	The response contains a status for the operation and the height according to the heuristic (currently maximum value) in the units specified (by the `SetUnits` command) if the operation status was successful (i.e., 0). Upon failure, the error code is returned. Status indicates whether the query command was successful or whether an error was encountered. A status of 0 indicates the operation was a success. Otherwise, the error code is returned. If an error code is encountered, the clearance is not returned.
Example Request
Example Responses
Example CSV Responses

REST Endpoint & JSON Message Definition

Endpoint
Supported Operations	GET
Function Description	The heights endpoint provides callers the height according to the heuristic of maximum value within a specified area. The parameters are the centroid 2D point (cx, cy) and the width and length of the area of interest (all units in meters).
Response Details	The response is the maximum height in meters.
Example Request
Example Response

Change Detection(under development)

General description

Users can inspect a volume for deviations from a expected template built by adding objects to a volume and then querying for the deviations.

Users can create, read, update, and delete change detection filter objects and adjust their parameters. Creation of filter objects and adjusting the filter parameters can only be performed via the REST interface. To query the filter for changes, users have the option of using the ASCII interface or the REST interface.

Endpoints
Supported Operations	GET, PATCH, POST, PUT, and DELETE
Base Endpoints

Create (filter)

To create an instance of the change detection filter, users must POST on the /changes endpoint, providing the volume ID within the request body.

Operation	POST
Description	Creates a volume.
Request
Request Body Format
Response Body Format
Example Response Body

Read (filter)

To read a list of all change detection filters configured in RapidSense, users can perform a GET on the /changes endpoint and receive a list of all filters with their IDs and attributes and objects added to the volume.

Operation	GET
Description	Returns a list of all configured filters in the system.
Request
Response Body Format
Example Response Body

Update (filter)

To update a filter’s parameter(s), users can perform a PUT on /changes/<id>.

Operation	PUT
Description	Creates a volume.
Request
Request Body Format
Response Body Format
Example Response Body

Delete (filter)

To remove / delete a change detection filter, users DELETE on the /changes/<id> endpoint providing the ID to remove.

Operation	DELETE
Description	Removes a change detection filter.
Request
Request Body Format	None.
Response Body Format	None.