hvl_ccb.dev.newport

Device class for Newport SMC100PP stepper motor controller with serial communication.

The SMC100PP is a single axis motion controller/driver for stepper motors up to 48 VDC at 1.5 A rms. Up to 31 controllers can be networked through the internal RS-485 communication link.

Manufacturer homepage: https://www.newport.com/f/smc100-single-axis-dc-or-stepper-motion-controller

class NewportConfigCommands(value=<no_arg>, names=None, module=None, type=None, start=1, boundary=None)

Bases: hvl_ccb.utils.enum.NameEnum

Commands predefined by the communication protocol of the SMC100PP

AC = 'acceleration'

BA = 'backlash_compensation'

BH = 'hysteresis_compensation'

FRM = 'micro_step_per_full_step_factor'

FRS = 'motion_distance_per_full_step'

HT = 'home_search_type'

JR = 'jerk_time'

OH = 'home_search_velocity'

OT = 'home_search_timeout'

QIL = 'peak_output_current_limit'

SA = 'rs485_address'

SL = 'negative_software_limit'

SR = 'positive_software_limit'

VA = 'velocity'

VB = 'base_velocity'

ZX = 'stage_configuration'

exception NewportControllerError

Bases: Exception

Error with the Newport controller.

exception NewportMotorError

Bases: Exception

Error with the Newport motor.

exception NewportMotorPowerSupplyWasCutError

Bases: Exception

Error with the Newport motor after the power supply was cut and then restored, without interrupting the communication with the controller.

class NewportSMC100PP(com, dev_config=None)

Bases: hvl_ccb.dev.base.SingleCommDevice

Device class of the Newport motor controller SMC100PP

class MotorErrors(value=<no_arg>, names=None, module=None, type=None, start=1, boundary=None)

Bases: aenum.Enum

Possible motor errors reported by the motor during get_state().

DC_VOLTAGE_TOO_LOW = 3

FOLLOWING_ERROR = 6

HOMING_TIMEOUT = 5

NED_END_OF_TURN = 11

OUTPUT_POWER_EXCEEDED = 2

PEAK_CURRENT_LIMIT = 9

POS_END_OF_TURN = 10

RMS_CURRENT_LIMIT = 8

SHORT_CIRCUIT = 7

WRONG_ESP_STAGE = 4

class StateMessages(value=<no_arg>, names=None, module=None, type=None, start=1, boundary=None)

Bases: aenum.Enum

Possible messages returned by the controller on get_state() query.

CONFIG = '14'

DISABLE_FROM_JOGGING = '3E'

DISABLE_FROM_MOVING = '3D'

DISABLE_FROM_READY = '3C'

HOMING_FROM_RS232 = '1E'

HOMING_FROM_SMC = '1F'

JOGGING_FROM_DISABLE = '47'

JOGGING_FROM_READY = '46'

MOVING = '28'

NO_REF_ESP_STAGE_ERROR = '10'

NO_REF_FROM_CONFIG = '0C'

NO_REF_FROM_DISABLED = '0D'

NO_REF_FROM_HOMING = '0B'

NO_REF_FROM_JOGGING = '11'

NO_REF_FROM_MOVING = '0F'

NO_REF_FROM_READY = '0E'

NO_REF_FROM_RESET = '0A'

READY_FROM_DISABLE = '34'

READY_FROM_HOMING = '32'

READY_FROM_JOGGING = '35'

READY_FROM_MOVING = '33'

States

alias of hvl_ccb.dev.newport.NewportStates

static config_cls()

Return the default configdataclass class.

Returns

a reference to the default configdataclass class

static default_com_cls()

Get the class for the default communication protocol used with this device.

Returns

the type of the standard communication protocol for this device

exit_configuration(add: Optional[int] = None) → None

Exit the CONFIGURATION state and go back to the NOT REFERENCED state. All configuration parameters are saved to the device”s memory.

Parameters

add – controller address (1 to 31)

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

get_acceleration(add: Optional[int] = None) → Union[int, float]

Leave the configuration state. The configuration parameters are saved to the device”s memory.

Parameters

add – controller address (1 to 31)

Returns

acceleration (preset units/s^2), value between 1e-6 and 1e12

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

get_controller_information(add: Optional[int] = None) → str

Get information on the controller name and driver version

Parameters

add – controller address (1 to 31)

Returns

controller information

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

get_motor_configuration(add: Optional[int] = None) → Dict[str, float]

Query the motor configuration and returns it in a dictionary.

Parameters

add – controller address (1 to 31)

Returns

dictionary containing the motor’s configuration

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

get_move_duration(dist: Union[int, float], add: Optional[int] = None) → float

Estimate the time necessary to move the motor of the specified distance.

Parameters

• dist – distance to travel

• add – controller address (1 to 31), defaults to self.address

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

get_negative_software_limit(add: Optional[int] = None) → Union[int, float]

Get the negative software limit (the maximum position that the motor is allowed to travel to towards the left).

Parameters

add – controller address (1 to 31)

Returns

negative software limit (preset units), value between -1e12 and 0

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

get_position(add: Optional[int] = None) → float

Returns the value of the current position.

Parameters

add – controller address (1 to 31)

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

• NewportUncertainPositionError – if the position is ambiguous

get_positive_software_limit(add: Optional[int] = None) → Union[int, float]

Get the positive software limit (the maximum position that the motor is allowed to travel to towards the right).

Parameters

add – controller address (1 to 31)

Returns

positive software limit (preset units), value between 0 and 1e12

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

get_state(add: int = None) → StateMessages

Check on the motor errors and the controller state

Parameters

add – controller address (1 to 31)

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

• NewportMotorError – if the motor reports an error

Returns

state message from the device (member of StateMessages)

go_home(add: Optional[int] = None) → None

Move the motor to its home position.

Parameters

add – controller address (1 to 31), defaults to self.address

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

go_to_configuration(add: Optional[int] = None) → None

This method is executed during start(). It can also be executed after a reset(). The controller is put in CONFIG state, where configuration parameters can be changed.

Parameters

add – controller address (1 to 31)

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

initialize(add: Optional[int] = None) → None

Puts the controller from the NOT_REF state to the READY state. Sends the motor to its “home” position.

Parameters

add – controller address (1 to 31)

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

move_to_absolute_position(pos: Union[int, float], add: Optional[int] = None) → None

Move the motor to the specified position.

Parameters

• pos – target absolute position (affected by the configured offset)

• add – controller address (1 to 31), defaults to self.address

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

move_to_relative_position(pos: Union[int, float], add: Optional[int] = None) → None

Move the motor of the specified distance.

Parameters

• pos – distance to travel (the sign gives the direction)

• add – controller address (1 to 31), defaults to self.address

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

reset(add: Optional[int] = None) → None

Resets the controller, equivalent to a power-up. This puts the controller back to NOT REFERENCED state, which is necessary for configuring the controller.

Parameters

add – controller address (1 to 31)

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

set_acceleration(acc: Union[int, float], add: Optional[int] = None) → None

Leave the configuration state. The configuration parameters are saved to the device”s memory.

Parameters

• acc – acceleration (preset units/s^2), value between 1e-6 and 1e12

• add – controller address (1 to 31)

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

set_motor_configuration(add: Optional[int] = None, config: Optional[dict] = None) → None

Set the motor configuration. The motor must be in CONFIG state.

Parameters

• add – controller address (1 to 31)

• config – dictionary containing the motor’s configuration

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

set_negative_software_limit(lim: Union[int, float], add: Optional[int] = None) → None

Set the negative software limit (the maximum position that the motor is allowed to travel to towards the left).

Parameters

• lim – negative software limit (preset units), value between -1e12 and 0

• add – controller address (1 to 31)

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

set_positive_software_limit(lim: Union[int, float], add: Optional[int] = None) → None

Set the positive software limit (the maximum position that the motor is allowed to travel to towards the right).

Parameters

• lim – positive software limit (preset units), value between 0 and 1e12

• add – controller address (1 to 31)

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

start()

Opens the communication protocol and applies the config.

Raises

SerialCommunicationIOError – when communication port cannot be opened

stop() → None

Stop the device. Close the communication protocol.

stop_motion(add: Optional[int] = None) → None

Stop a move in progress by decelerating the positioner immediately with the configured acceleration until it stops. If a controller address is provided, stops a move in progress on this controller, else stops the moves on all controllers.

Parameters

add – controller address (1 to 31)

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

wait_until_motor_initialized(add: Optional[int] = None) → None

Wait until the motor leaves the HOMING state (at which point it should have arrived to the home position).

Parameters

add – controller address (1 to 31)

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

class NewportSMC100PPConfig(address: int = 1, user_position_offset: Union[int, float] = 23.987, screw_scaling: Union[int, float] = 1, exit_configuration_wait_sec: Union[int, float] = 5, move_wait_sec: Union[int, float] = 1, acceleration: Union[int, float] = 10, backlash_compensation: Union[int, float] = 0, hysteresis_compensation: Union[int, float] = 0.015, micro_step_per_full_step_factor: int = 100, motion_distance_per_full_step: Union[int, float] = 0.01, home_search_type: Union[int, hvl_ccb.dev.newport.NewportSMC100PPConfig.HomeSearch] = HomeSearch.HomeSwitch, jerk_time: Union[int, float] = 0.04, home_search_velocity: Union[int, float] = 4, home_search_timeout: Union[int, float] = 27.5, home_search_polling_interval: Union[int, float] = 1, peak_output_current_limit: Union[int, float] = 0.4, rs485_address: int = 2, negative_software_limit: Union[int, float] = - 23.5, positive_software_limit: Union[int, float] = 25, velocity: Union[int, float] = 4, base_velocity: Union[int, float] = 0, stage_configuration: Union[int, hvl_ccb.dev.newport.NewportSMC100PPConfig.EspStageConfig] = EspStageConfig.EnableEspStageCheck)

Bases: object

Configuration dataclass for the Newport motor controller SMC100PP.

class EspStageConfig(value=<no_arg>, names=None, module=None, type=None, start=1, boundary=None)

Bases: aenum.IntEnum

Different configurations to check or not the motor configuration upon power-up.

DisableEspStageCheck = 1

EnableEspStageCheck = 3

UpdateEspStageInfo = 2

class HomeSearch(value=<no_arg>, names=None, module=None, type=None, start=1, boundary=None)

Bases: aenum.IntEnum

Different methods for the motor to search its home position during initialization.

CurrentPosition = 1

EndOfRunSwitch = 4

EndOfRunSwitch_and_Index = 3

HomeSwitch = 2

HomeSwitch_and_Index = 0

acceleration: Union[int, float] = 10

address: int = 1

backlash_compensation: Union[int, float] = 0

base_velocity: Union[int, float] = 0

clean_values()

exit_configuration_wait_sec: Union[int, float] = 5

force_value(fieldname, value)

Forces a value to a dataclass field despite the class being frozen.

NOTE: you can define post_force_value method with same signature as this method to do extra processing after value has been forced on fieldname.

Parameters

• fieldname – name of the field

• value – value to assign

home_search_polling_interval: Union[int, float] = 1

home_search_timeout: Union[int, float] = 27.5

home_search_type: Union[int, hvl_ccb.dev.newport.NewportSMC100PPConfig.HomeSearch] = 2

home_search_velocity: Union[int, float] = 4

hysteresis_compensation: Union[int, float] = 0.015

is_configdataclass = True

jerk_time: Union[int, float] = 0.04

classmethod keys() → Sequence[str]

Returns a list of all configdataclass fields key-names.

Returns

a list of strings containing all keys.

micro_step_per_full_step_factor: int = 100

motion_distance_per_full_step: Union[int, float] = 0.01

property motor_config: Dict[str, float]

Gather the configuration parameters of the motor into a dictionary.

Returns

dict containing the configuration parameters of the motor

move_wait_sec: Union[int, float] = 1

negative_software_limit: Union[int, float] = -23.5

classmethod optional_defaults() → Dict[str, object]

Returns a list of all configdataclass fields, that have a default value assigned and may be optionally specified on instantiation.

Returns

a list of strings containing all optional keys.

peak_output_current_limit: Union[int, float] = 0.4

positive_software_limit: Union[int, float] = 25

post_force_value(fieldname, value)

classmethod required_keys() → Sequence[str]

Returns a list of all configdataclass fields, that have no default value assigned and need to be specified on instantiation.

Returns

a list of strings containing all required keys.

rs485_address: int = 2

screw_scaling: Union[int, float] = 1

stage_configuration: Union[int, hvl_ccb.dev.newport.NewportSMC100PPConfig.EspStageConfig] = 3

user_position_offset: Union[int, float] = 23.987

velocity: Union[int, float] = 4

class NewportSMC100PPSerialCommunication(configuration)

Bases: hvl_ccb.comm.serial.SerialCommunication

Specific communication protocol implementation for NewportSMC100 controller. Already predefines device-specific protocol parameters in config.

class ControllerErrors(value=<no_arg>, names=None, module=None, type=None, start=1, boundary=None)

Bases: aenum.Enum

Possible controller errors with values as returned by the device in response to sent commands.

ADDR_INCORRECT = 'B'

CMD_EXEC_ERROR = 'V'

CMD_NOT_ALLOWED = 'D'

CMD_NOT_ALLOWED_CC = 'X'

CMD_NOT_ALLOWED_CONFIGURATION = 'I'

CMD_NOT_ALLOWED_DISABLE = 'J'

CMD_NOT_ALLOWED_HOMING = 'L'

CMD_NOT_ALLOWED_MOVING = 'M'

CMD_NOT_ALLOWED_NOT_REFERENCED = 'H'

CMD_NOT_ALLOWED_PP = 'W'

CMD_NOT_ALLOWED_READY = 'K'

CODE_OR_ADDR_INVALID = 'A'

COM_TIMEOUT = 'S'

DISPLACEMENT_OUT_OF_LIMIT = 'G'

EEPROM_ACCESS_ERROR = 'U'

ESP_STAGE_NAME_INVALID = 'F'

HOME_STARTED = 'E'

NO_ERROR = '@'

PARAM_MISSING_OR_INVALID = 'C'

POSITION_OUT_OF_LIMIT = 'N'

check_for_error(add: int) → None

Ask the Newport controller for the last error it recorded.

This method is called after every command or query.

Parameters

add – controller address (1 to 31)

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

static config_cls()

Return the default configdataclass class.

Returns

a reference to the default configdataclass class

query(add: int, cmd: str, param: Optional[Union[int, float, str]] = None) → str

Send a query to the controller, read the answer, and check for errors. The prefix add+cmd is removed from the answer.

Parameters

• add – the controller address (1 to 31)

• cmd – the command to be sent

• param – optional parameter (int/float/str) appended to the command

Returns

the answer from the device without the prefix

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

query_multiple(add: int, cmd: str, prefixes: List[str]) → List[str]

Send a query to the controller, read the answers, and check for errors. The prefixes are removed from the answers.

Parameters

• add – the controller address (1 to 31)

• cmd – the command to be sent

• prefixes – prefixes of each line expected in the answer

Returns

list of answers from the device without prefix

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

read_text() → str

Read one line of text from the serial port, and check for presence of a null char which indicates that the motor power supply was cut and then restored. The input buffer may hold additional data afterwards, since only one line is read.

This method uses self.access_lock to ensure thread-safety.

Returns

String read from the serial port; ‘’ if there was nothing to read.

Raises

• SerialCommunicationIOError – when communication port is not opened

• NewportMotorPowerSupplyWasCutError – if a null char is read

send_command(add: int, cmd: str, param: Optional[Union[int, float, str]] = None) → None

Send a command to the controller, and check for errors.

Parameters

• add – the controller address (1 to 31)

• cmd – the command to be sent

• param – optional parameter (int/float/str) appended to the command

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

• NewportControllerError – if the controller reports an error

send_stop(add: int) → None

Send the general stop ST command to the controller, and check for errors.

Parameters

add – the controller address (1 to 31)

Returns

ControllerErrors reported by Newport Controller

Raises

• SerialCommunicationIOError – if the com is closed

• NewportSerialCommunicationError – if an unexpected answer is obtained

class NewportSMC100PPSerialCommunicationConfig(terminator: bytes = b'\r\n', encoding: str = 'ascii', encoding_error_handling: str = 'replace', wait_sec_read_text_nonempty: Union[int, float] = 0.5, default_n_attempts_read_text_nonempty: int = 10, port: Union[str, NoneType] = None, baudrate: int = 57600, parity: Union[str, hvl_ccb.comm.serial.SerialCommunicationParity] = <SerialCommunicationParity.NONE: 'N'>, stopbits: Union[int, hvl_ccb.comm.serial.SerialCommunicationStopbits] = <SerialCommunicationStopbits.ONE: 1>, bytesize: Union[int, hvl_ccb.comm.serial.SerialCommunicationBytesize] = <SerialCommunicationBytesize.EIGHTBITS: 8>, timeout: Union[int, float] = 10)

Bases: hvl_ccb.comm.serial.SerialCommunicationConfig

baudrate: int = 57600

Baudrate for NewportSMC100 controller is 57600 baud

bytesize: Union[int, hvl_ccb.comm.serial.SerialCommunicationBytesize] = 8

NewportSMC100 controller uses 8 bits for one data byte

encoding: str = 'ascii'

use ASCII as de-/encoding, cf. the manual

encoding_error_handling: str = 'replace'

replace bytes with � instead of raising utf-8 exception when decoding fails

force_value(fieldname, value)

Forces a value to a dataclass field despite the class being frozen.

NOTE: you can define post_force_value method with same signature as this method to do extra processing after value has been forced on fieldname.

Parameters

• fieldname – name of the field

• value – value to assign

classmethod keys() → Sequence[str]

Returns a list of all configdataclass fields key-names.

Returns

a list of strings containing all keys.

classmethod optional_defaults() → Dict[str, object]

Returns a list of all configdataclass fields, that have a default value assigned and may be optionally specified on instantiation.

Returns

a list of strings containing all optional keys.

parity: Union[str, hvl_ccb.comm.serial.SerialCommunicationParity] = 'N'

NewportSMC100 controller does not use parity

classmethod required_keys() → Sequence[str]

Returns a list of all configdataclass fields, that have no default value assigned and need to be specified on instantiation.

Returns

a list of strings containing all required keys.

stopbits: Union[int, hvl_ccb.comm.serial.SerialCommunicationStopbits] = 1

NewportSMC100 controller uses one stop bit

terminator: bytes = b'\r\n'

The terminator is CR/LF

timeout: Union[int, float] = 10

use 10 seconds timeout as default

exception NewportSerialCommunicationError

Bases: Exception

Communication error with the Newport controller.

class NewportStates(value=<no_arg>, names=None, module=None, type=None, start=1, boundary=None)

Bases: hvl_ccb.utils.enum.AutoNumberNameEnum

States of the Newport controller. Certain commands are allowed only in certain states.

CONFIG = 3

DISABLE = 6

HOMING = 2

JOGGING = 7

MOVING = 5

NO_REF = 1

READY = 4

exception NewportUncertainPositionError

Bases: Exception

Error with the position of the Newport motor.