APIs, concepts, guides, and more

🔹 RPCs

rpc Axis (AxisRequest) returns (AxisResponse) {};
rpc AxisBatch (AxisBatchRequest) returns (AxisBatchResponse) {};

🔹 Request

message AxisRequest {
// Common request header
RSI.RapidServer.RequestHeader header = 1;
// Axis index
int32 index = 2;
optional AxisConfig config = 3;
optional AxisAction action = 4;
}

🔹 Response

message AxisResponse {
// Common response header. Always check the response header for errors.
RSI.RapidServer.ResponseHeader header = 1;
// Axis index
int32 index = 2;
optional AxisConfig config = 3;
optional AxisAction action = 4;
optional AxisInfo info = 5;
optional AxisStatus status = 6;
}

🔹 Batch Request and Response

message AxisBatchRequest {
// Common request header
RSI.RapidServer.RequestHeader header = 1;
repeated AxisRequest requests = 2;
}
message AxisBatchResponse {
// Common response header. Always check the response header for errors.
RSI.RapidServer.ResponseHeader header = 1;
repeated AxisResponse responses = 2;
}

🔹 Config

message AxisConfig {
// The number of encoder counts to UserUnits.
optional double user_units = 1;
// The origin position, typically set when homing.
optional double origin_position = 2;
// Give the Axis a name, if you like.
optional string user_label = 3;
// Default trajectory values.
optional TrajectoryDefaults defaults = 4;
optional HardwareTrigger amp_fault = 5;
optional HardwareTrigger home_switch = 6;
optional ErrorLimit error_limit = 7;
optional HardwareTrigger hardware_negative_limit = 8;
optional HardwareTrigger hardware_positive_limit = 9;
optional SoftwareTrigger software_negative_limit = 10;
optional SoftwareTrigger software_positive_limit = 11;
optional Settling settling = 12;
optional MotionConfig motion = 13;
optional Homing homing = 14;
optional int32 frame_buffer_size = 15;
optional RSIMotorDisableAction amp_disable_action = 16;
// Internal messages.
message TrajectoryDefaults
{
optional double velocity = 1;
optional double acceleration = 2;
optional double deceleration = 3;
optional double jerk_percent = 4;
optional double position1 = 5;
optional double position2 = 6;
optional double relative_increment = 7;
}
message HardwareTrigger {
optional RSIAction action = 1;
optional bool trigger_state = 2;
optional double duration = 3;
}
message SoftwareTrigger {
optional RSIAction action = 1;
optional double trigger_value = 2;
}
message ErrorLimit {
optional RSIAction action = 1;
optional double trigger_value = 2;
optional double duration = 3;
}
message Settling {
optional double position_tolerance_fine = 1;
optional double position_tolerance_coarse = 2;
optional double velocity_tolerance = 3;
optional double time_seconds = 4;
optional bool on_stop = 5;
optional bool on_estop = 6;
optional bool on_estop_cmd_equals_actual = 7;
}
message MotionConfig {
// Seconds.
optional double stop_time = 1;
// Seconds.
optional double estop_time = 2;
// UserUnits per second.
optional double triggered_modify_deceleration = 3;
// Jerk percent (0-100).
optional double triggered_modify_jerk_percent = 4;
// UserUnits per second.
optional double estop_modify_deceleration = 5;
// Jerk percent (0-100).
optional double estop_modify_jerk_percent = 6;
}
message Homing {
optional RSIHomeMethod method = 1;
optional double offset = 2;
optional double velocity = 3; // this requires the home stage?
optional double slow_velocity = 4;
optional double acceleration = 5; // this requires the home stage?
optional double deceleration = 6; // this requires the home stage?
optional double jerk_percent = 7;
optional bool state = 8;
optional RSIHomeStage stage = 9;
optional RSIAction behavior = 10;
}
}

🔹 Action

message AxisAction {
optional Abort abort = 1;
optional EStopAbort e_stop_abort = 2;
optional EStopModifyAbort e_stop_modify_abort = 3;
optional EStopModify e_stop_modify = 4;
optional EStop e_stop = 5;
optional TriggeredModify triggered_modify = 6;
optional Stop stop = 7;
optional Resume resume = 8;
optional ClearFaults clear_faults = 9;
optional AmpEnable amp_enable = 10;
optional AmpDisable amp_disable = 11;
optional HoldGateSet hold_gate_set = 12;
optional PositionSet position_set = 13;
optional Move move = 14;
optional GearEnable gear_enable = 15;
optional GearDisable gear_disable = 16;
optional Home home = 17;
optional HomeCancel home_cancel = 18;
message Abort {}
message EStopAbort {}
message EStopModifyAbort{}
message EStopModify{}
message EStop {}
message TriggeredModify {}
message Stop {}
message Resume {}
message ClearFaults {}
message AmpEnable {
optional int32 timeout_milliseconds = 1;
optional int32 duration = 2; // read-only how long did it take to enable? only set if you specify a timeout to wait for AMP_ACTIVE
}
message AmpDisable {}
message HoldGateSet {
bool state = 1;
}
message PositionSet{
double position = 1;
}
message Move {
// Request one type of motion.
oneof move {
AxisMovePointToPoint point_to_point = 3;
AxisMoveVelocity velocity = 4;
MoveStreaming streaming = 5;
}
// Specify the MotionID for this move. (If you don't specify one, it will be auto-incremented after each move.)
optional uint32 motion_id = 6;
// Specify MotionHold criteria, if you want the motion to hold execution until conditions are met.
optional MotionHold motion_hold = 7;
// Wait for motion to complete? (See ConfigSet settling criteria.)
bool blocking = 8;
}
message GearEnable {
optional int32 master_axis_number = 2;
optional RSIAxisMasterType gearing_source = 3;
int32 numerator = 4;
int32 denominator = 5;
}
message GearDisable {}
message Home {
optional bool move_to_zero = 1;
}
message HomeCancel {}
}
// Internal MoveRequest messages.
message AxisMovePointToPoint {
// Move to this position. Absolute, unless the relative boolean is true. (UserUnits)
double position = 1;
// Maximum velocity. (UserUnits/second).
optional double velocity = 2;
// Maximum acceleration. (UserUnits/second^2). If specified, velocity and deceleration must be specified.
optional double acceleration = 3;
// Maximum deceleration. (UserUnits/second^2). If specified, velocity and acceleration must be specified
optional double deceleration = 4;
// Percentage of acceleration that will be smoothed. (0-100)
// Acceleration time will not change so if Jerk Percent is 100, maximum acceleration will be 2x the specified maximum.
// If specified, velocity, acceleration, and deceleration must be specified.
optional double jerk_percent = 5;
// Final velocity. 0.0 is default. (UserUnits/second)
// If specified, velocity, acceleration, and decleration must be specified.
optional double final_velocity = 6;
// Set true if you intend position to be a relative increment. If specified, jerk_percent must be specified.
bool relative = 7;
}
message AxisMoveVelocity {
// Move at this velocity. (UserUnits/second)
double velocity = 1;
// Maximum acceleration. (UserUnits/second^2)
double acceleration = 2;
// Percentage of acceleration that will be smoothed. (0-100)
// Acceleration time will not change so if Jerk Percent is 100, maximum acceleration will be 2x the specified maximum.
double jerk_percent = 3;
}
message MoveStreaming {
repeated double positions = 1;
repeated double velocities = 2;
repeated double accelerations = 3;
repeated double jerks = 4;
repeated double times = 5;
int32 empty_count = 6;
bool retain = 7;
bool final = 8;
// Specify the interpolation algorithm to use when only providing positions and no velocities nor accelerations.
// Uses the RapidCode method RapidCodeMotion::MovePT()
// The three currently supported ones are:
// RSIMotionTypePT (no interpolation)
// RSIMotionTypeBSPLINE (default)
// RSIMotionTypePVT is used in the RapidCode method RapidCodeMotion::MovePVT(), i.e. when positions and velocities are given.
optional RSIMotionType pt_motion_type = 9;
}

🔹 Info

message AxisInfo {
// Axis index.
int32 index = 1;
// Host and firmware addresses
repeated AddressInfo addresses = 2;
// NetworkNode information.
NetworkNodeInfo node_info = 3;
// Constants from the Axis object
Constants constants = 4;
// The internal motion supervisor index
int32 motion_supervisor_index = 5;
message Constants {
// The value returned by NetworkIndexGet() when the index is invalid or nonexistent for this Axis.
uint32 network_index_invalid = 1;
// The default time an Axis waits before generating an AmpFault if the Axis does not enable after calling AmpEnableSet(true).
double amp_enable_amp_fault_timeout_seconds_default = 2;
}
}

🔹 Status

message AxisStatus {
// Is the amp enabled?
bool amp_enabled = 1;
// The state (IDLE, MOVING, ERROR, etc.).
RSIState state = 2;
// The cause of the error (if in ERROR, STOPPED, STOPPING_ERROR state).
RSISource source = 3;
// Extra fault info from the drive
string source_name = 4;
// Positions.
PositionStatus position = 5;
// Command and actual velocity.
VelocityStatus velocity = 6;
// Command acceleration.
AccelerationStatus acceleration = 7;
// How many frames does the Axis have left to execute?
int32 frames_to_execute = 8;
// The motion id as stored in the Axis class (unsigned 16-bit integer).
uint32 motion_id = 9;
// The currently executing motion identifier (unsigned 16-bit integer).
uint32 motion_id_executing = 10;
// The currently exeucting motion element identifier (unsigned 16-bit integer).
int32 element_id_executing = 11;
// Is electronic gearing enabled?
bool gear_enabled = 12;
// Status bits related to the motor.
MotorStatusBits motor_status_bits = 13;
// Status bits related to motion.
MotionStatusBits motion_status_bits = 14;
// DS402 status bits, for drives that support DS402.
Ds402StatusBits ds402_status_bits = 15;
// Dedicated output bits.
DedicatedOutputBits dedicated_output_bits = 16;
// Dedicated input bits.
DedicatedInputBits dedicated_input_bits = 17;
message PositionStatus {
double command = 1;
double actual = 2;
double error = 3;
double target = 4;
double origin = 5;
double encoder_0 = 6;
double encoder_1 = 7;
double compensation = 8;
double backlash = 9;
}
message VelocityStatus {
double command = 1;
double actual = 2;
}
message AccelerationStatus {
double command = 1;
}
message MotorStatusBits {
bool amp_fault = 1;
bool amp_warning = 2;
bool feedback_fault = 3;
bool limit_position_error = 4;
bool limit_torque = 5;
bool limit_hardware_negative = 6;
bool limit_hardware_positive = 7;
bool limit_software_negative = 8;
bool limit_software_positive = 9;
}
message MotionStatusBits {
bool done = 1;
bool start = 2;
bool modify = 3;
bool at_velocity = 4;
bool out_of_frames = 5;
bool near_target = 6;
bool at_target = 7;
bool settled = 8;
}
message Ds402StatusBits {
bool ready_to_switch_on = 1;
bool switched_on = 2;
bool operation_enabled = 3;
bool fault = 4;
bool voltage_enabled = 5;
bool quick_stop = 6;
bool switch_on_disabled = 7;
bool warning = 8;
bool manufacturer_specific_8 = 9;
bool remote = 10;
bool target_reached = 11;
bool internal_limit_active = 12;
bool operation_mode_specific_12 = 13;
bool operation_mode_specific_13 = 14;
bool manufacturer_specific_14 = 15;
bool manufacturer_specific_15 = 16;
}
message DedicatedOutputBits {
bool amp_enable = 1;
bool brake_release = 2;
}
message DedicatedInputBits {
bool amp_fault = 1;
bool brake_applied = 2;
bool home = 3;
bool limit_hardware_positive = 4;
bool limit_hardware_negative = 5;
bool index = 6;
bool index_secondary = 7;
bool feedback_fault = 8;
bool captured = 9;
bool hall_a = 10;
bool hall_b = 11;
bool hall_c = 12;
bool amp_active = 13;
bool warning = 14;
bool drive_status_9 = 15;
bool drive_status_10 = 16;
bool feedback_fault_primary = 17;
bool feedback_fault_secondary = 18;
}
}