Overview

This document provides a description of the API (REST Endpoints) that are used to access and control the Rook nanopositioner.

REST Endpoints

All URLs below are relative to http://ipaddress:47171/v1, unless noted otherwise. 47171 is the port used for remote control of a Rook nanopositioner.

A list of all available endpoints for your instrument can be viewed by browsing to http://ipaddress:47171. Firefox is our preferred browser for viewing the endpoints as they are displayed in a nice manner and are live hyperlinks that can be used to browse around the instruments endpoints. This is a great way to get familiar with the endpoints in your instrument and do simple exploring of your system.

Resource Summary

This instrument is made up of 1-4 nanopositioner stacks and each stack consists of 3 axes that can be controlled independently.

Endpoint Organization	Description
/stacks/stack{M}/axes/axis{N}	Contains all endpoints related to axis N where M is the stack number [1-4] and N is the axis number [1-3].

The methods and properties for each of these endpoints is described below.

Note: All data values are in SI units, unless noted otherwise.

Warning: Any endpoints not documented are not intended for customer use and are not guaranteed to be stable or tested and may change in the future.

Axis Resources

All URLs below are relative to a axis resource, unless noted otherwise. For example, http://ipaddress:port/v1/stacks/stack1/axes/axis3 would be the base part of the URL used to get to stack 1, axis 3. All URLs in this section would be appended to this base URL to get the full URL.

Axis Methods

Jog

HTTP request	Description
POST /methods/jog(JogDirection:dir)	Moves the axis continuously in a direction with no target position.

Data:

{
  "dir": string
}

Valid values for dir:

Positive
Negative

The jog commands will continue moving the axis continuously until a subsequent Stop command is sent. If hard stop detection is enabled, the axis will be stopped automatically if a hard stop is detected while jogging.

Warning: Jogging an axis continuously for more than a few seconds can decrease the overall lifetime and performance of the nanopositioner.

Move Absolute

HTTP request	Description
POST /methods/moveAbsolute(double:pos)	Moves the axis to the given absolute position (m).

Stop

HTTP request	Description
POST /methods/stop()	Stops all axis motion and resets the target position to the current encoder position.

Zero

HTTP request	Description
POST /methods/zero()	Set the current position as absolute zero.

Axis Properties

Closed Loop Deadband Counts

HTTP request	Description
GET /properties/closedLoopDeadbandCounts	Gets the number of encoder counts that define the Closed Loop deadband region.
PUT /properties/closedLoopDeadbandCounts	Sets the number of encoder counts that define the Closed Loop deadband region.

Data:

{
  "closedLoopDeadbandCounts": number
}

Closed Loop Deadband Timeout

HTTP request	Description
GET /properties/closedLoopDeadbandTimeout	Gets the amount of time (seconds) that the controller will try to move into the deadband area.
PUT /properties/closedLoopDeadbandTimeout	Sets the amount of time (seconds) that the controller will try to move into the deadband area.

Data:

{
  "closedLoopDeadbandTimeout": number
}

Feedback Mode

HTTP request	Description
GET /properties/feedbackMode	Gets the feedback mode.
PUT /properties/feedbackMode	Sets the feedback mode.

Data:

{
  "feedbackMode": string
}

Valid values for feedbackMode:

OpenLoop
ClosedLoop

Warning: Cannot change feedback mode while an axis is moving.

Hard Stop Detection Enabled

HTTP request	Description
GET /properties/hardStopDetectionEnabled	Gets whether hard stop detection is enabled.
PUT /properties/hardStopDetectionEnabled	Sets whether hard stop detection is enabled.

Data:

{
  "hardStopDetectionEnabled": bool
}

Warning: Cannot change hard stop detection enabled while an axis is moving.

Hard Stop Rebound Distance

HTTP request	Description
GET /properties/hardStopReboundDistance	Gets the rebound distance (m) after a hard stop is detected.
PUT /properties/hardStopReboundDistance	Sets the rebound distance (m) after a hard stop is detected.

Data:

{
  "hardStopReboundDistance": number
}

Warning: Cannot change hard stop rebound distance while an axis is moving.

Hard Stop Sensitivity

HTTP request	Description
GET /properties/hardStopSensitivity	Gets the sensitivity (1-100) of the hard stop detection.
PUT /properties/hardStopSensitivity	Sets the sensitivity (1-100) of the hard stop detection.

Data:

{
  "hardStopSensitivity": number
}

The sensitivity is a value from 1 - 100, with 1 being the least sensitive and 100 being the most sensitive.

Warning: Cannot change hard stop sensitivity while an axis is moving.

Have Feedback

HTTP request	Description
GET /properties/haveFeedback	Gets whether the axis has feedback encoders to measure position.

Data:

{
  "haveFeedback": bool
}

Name

HTTP request	Description
GET /properties/name	Gets the name of the axis.
PUT /properties/name	Sets the name of the axis.

Data:

{
  "name": string
}

Status

HTTP request	Description
GET /properties/status	Gets the status of the axis.

Data:

{
  "status":
  {
    "encoderPosition": number,
    "hardStopDetected": bool,
    "inPosition": bool,
    "moving": bool,
    "targetPosition": number,
    "theoreticalPosition": number,
    "timestamp": number
  }
}

Where status consists of:

encoderPosition	Current measured encoder position (m)
hardStopDetected	True if a hard stop was detected during the last move command.
inPosition	In Open Loop mode, true=axis has stopped moving, false=axis is moving. In Closed Loop mode, true=axis is in the deadband region around the target position, false=axis is out of deadband region.
moving	True if the axis is being moved by the motion controller.
targetPosition	The last commanded target position (m).

Velocity

HTTP request	Description
GET /properties/velocity	Gets the desired velocity (m/sec) of the axis.
PUT /properties/velocity	Sets the desired velocity (m/sec) of the axis.

Data:

{
  "velocity": number
}

Table of Contents

Overview

REST Endpoints

Resource Summary

Axis Resources

Axis Methods

Axis Properties