API¶

class ConnectionType(*values)¶

Returned by connection_type().

Ethernet = 1¶

Pci = 3¶

Serial = 2¶

class Controller(address: str)¶

class Controller(address: str, baud_rate: int)

Manages a connection to a controller.

address() → str¶: Returns the address that was used to connect to the controller.

array(array: str, start: int = 0, end: int = 0) → str¶

close() → None¶

command(command: str) → str¶

Issues a command to the controller and provides the response.

Note that a single command cannot be longer than 80 characters, similar to a program line.

Parameters:: command – Command to be sent to the controller. Will be terminated with a carriage return.
Returns:: The controller response.

connection_type() → ConnectionType¶: Returns the type of address that was used to connect to the controller.

data_record(timeout: int = -1) → DataRecord¶

Get a queued data record, or wait up to timeout ms for one to arrive.

Parameters:: timeout – Timeout value in milliseconds. If -1, wait forever.

interrupt(timeout: int = -1) → Interrupt¶

Get a queued interrupt, or wait up to timeout ms for one to arrive.

Parameters:: timeout – Timeout value in milliseconds. If -1, wait forever.

message(timeout: int = -1) → str¶

Get a queued message, or wait up to timeout ms for one to arrive.

Parameters:: timeout – Timeout value in milliseconds. If -1, wait forever.

open() → None¶: Reopen the connection. Only valid if close() has been called.

program() → str¶

revision_information() → str¶: Returns controller ^R^V output.

serial_number() → int¶

set_array(name: str, array: str, start: int = 0, end: int = 0) → None¶

set_data_records(period_ms: int) → None¶

Configure controller data records.

By default, data records are not sent by the controller.

See subscribe_data_records() to enable receiving data records from the controller.

Parameters:: period_ms – Period (in milliseconds) between data records. Pass 0 (default) to disable data records.

set_firmware(file_path: str) → None¶

set_interrupts(mask: Type, motion_complete_axes: int = 0, digital_inputs: int = 0) → None¶

Configure which interrupts will be generated by the controller.

By default, the controller will not generate any interrupts.

Controllers can be configured to send only an exact list of desired interrupts, to avoid unnecessary processing and network traffic.

Example usage:

>>> controller.set_interrupts(AllInterrupts) # Enable all interrupts.
>>> controller.set_interrupts(MotionComplete | DigitalInputLow, # Only enable two interrupts
  {0, 7}, # Only trigger MotionComplete on axis A or F
  {0, 3}) # Only trigger DigitalInputLow on digital input 1 and 4.
>>> controller.set_interrupts() # Disable interrupts

See subscribe_interrupts() to enable receiving interrupts from the controller.

Parameters:

interrupt_mask – Bitmask of desired interrupts. Use NoInterrupts (0) to disable interrupts. Note that User Interrupts cannot be disabled.
axis_mask – When MotionComplete is in interrupt_mask, this axis mask controls which axes will trigger a MotionComplete interrupt. If 0 (default), all axes will be selected.
digital_input_mask – When DigitalInputLow is in interrupt_mask, this bitmask selects which digital inputs will trigger an interrupt. If 0 (default), all digital inputs will be selected.

set_program(program: str, insert: str = '') → None¶

subscribe_data_records(callback: Callable[[DataRecord], None]) → None¶
subscribe_data_records() → None: Helper for @overload to raise when called.

subscribe_interrupts(callback: Callable[[Interrupt], None]) → None¶
subscribe_interrupts() → None: Helper for @overload to raise when called.

subscribe_messages(callback: Callable[[str], None]) → None¶
subscribe_messages() → None: Helper for @overload to raise when called.

subscribe_progress(callback: Callable[[int, int], None]) → None¶: Register a progress callback. This method registers a callback to be run every time data is written to thecontroller during a set_firmware, set_array, or set_program call. .. note:: The callback will be invoked on a separate, dedicated thread. Be careful when accessing any shared state. :param callback: A callback function, which will be invoked each time data is written to the controller. Replaces any previously set message callback.

unsubscribe_data_records() → None¶

unsubscribe_interrupts() → None¶

unsubscribe_messages() → None¶

unsubscribe_progress() → None¶

class DataRecord¶

class Amp¶

Holds amplifier-specific data record fields. Provided by DataRecord.amp().

Note

Amp errors are latched, and will need to be cleared with AZ once the underlying issue has been resolved. See the command reference for details.

electronic_lock_out() → bool¶

over_current() → bool¶

over_temp() → bool¶

over_voltage() → bool¶

under_voltage() → bool¶

class Axis¶

Holds axis-specific data record fields. Provided by DataRecord.axis().

class ModeOfMotion(*values)¶

Contour = 1¶

FindEdge = 4¶

FindIndex = 5¶

Home = 6¶

LinearMove = 7¶

NoMotion = 0¶

PositionAbsolute = 2¶

PositionRelative = 3¶

VectorMove = 7¶

analog_input() → float¶

aux_position() → int¶

final_deceleration() → bool¶

forward_limit() → bool¶

hall_error() → bool¶

halls() → int¶

home_input() → bool¶

home_phase() → int¶

latch_armed() → bool¶

latch_input() → bool¶

latch_occurred() → bool¶

mode_of_motion() → ModeOfMotion¶

motor_off() → bool¶

moving() → bool¶

negative_direction_move() → bool¶

peak_current() → bool¶

position() → int¶

position_error() → int¶

reference_position() → int¶

reverse_limit() → bool¶

slewing() → bool¶

stepper_mode() → bool¶

stop_code() → int¶

stopping() → bool¶

torque() → float¶

variable() → int¶

velocity() → int¶

class CoordinatedMove¶

Holds coordinated move specific data record fields. Provided by DataRecord.coordinated_move().

buffer_available() → int¶

distance() → int¶

final_deceleration() → bool¶

moving() → bool¶

segment_count() → int¶

slewing() → bool¶

status() → int¶

stopping() → bool¶

class EthernetStatus(*values)¶

EstablishingTcp = -6¶

EstablishingUdp = -5¶

HandleFree = 0¶

TcpMaster = -2¶

TcpSlave = 2¶

UdpMaster = -1¶

UdpSlave = 1¶

amp(index: int) → Amp¶: Get an instance of DataRecord.Amp, which provides amplifier-specific data record fields.

axis(axis: str) → Axis¶: Get an instance of DataRecord.Axis, which provides axis-specific data record fields.

bytes() → list[int]¶: Get data record as raw bytes. Useful if your device has a nonstandard data record.

contour_buffer_available() → int¶

contour_segment_count() → int¶

coordinated_move(plane: str) → CoordinatedMove¶: Get an instance of DataRecord.CoordinatedMove, which provides CM-specific data record fields.

error_code() → int¶

ethernet_status(handle: str) → EthernetStatus¶

Param:: handle The ethernet handle to check, A - H.

input(index: int) → bool¶

Note

Inputs are active low, meaning this function returns True if current is NOT flowing.

Param:: index The index of the input to check. Note that index 0 corresponds to @IN[1].
Returns:: True if input is active.

input_bank(index: int) → int¶

output(index: int) → bool¶

Param:: index The index of the output to check. Note that index 0 corresponds to @OUT[1].
Returns:: True if output is active.

output_bank(index: int) → int¶

sample() → int¶

thread_running(thread: int) → bool¶

exception Error¶: Thrown when the underlying C library returns a nonzero gclib_result.

class Interrupt¶

An unsolicited interrupt. Use Controller.set_interrupts to configure which types are generated by the controller, and Controller.subscribe_interrupts to receive generated interrupts from the controller.

class Type(*values)¶

Flags that can be combined to select which interrupts should be enabled by set_interrupts().Also used to categorize interrupts such as Interrupt.Type.MotionComplete which correspond to a range of status bytes.

AllAxesMotionComplete = 256¶

AllInterrupts = 65535¶

CommandDone = 16384¶

DigitalInputLow = 32768¶: Must be reenabled with set_interrupts() after each occurrence.

ExcessPositionError = 512¶: Must be reenabled with set_interrupts() after occurrence.

LimitSwitch = 1024¶: Must be reenabled with set_interrupts() after each occurrence.

MotionComplete = 1¶

NoInterrupts = 0¶

ProgramStopped = 8192¶: If multiple threads are running, this interrupt is only triggered when all threads are finished.

UserInterrupt = 0¶

WatchdogTimer = 2048¶

property axis: str¶: If type is MotionComplete, holds the axis that triggered the interrupt.

property digital_input: int¶: If type is DigitalInputLow, holds the digital input that triggered the interrupt.

property status: int¶: The raw status byte generated by the controller. See the EI command reference for all possible values.

property type: Type¶

property user_interrupt: int¶: If type is UserInterrupt, holds the user interrupt that was triggered.

class Result(*values)¶

BufferTooSmall = 5¶

CommandError = 4¶

InternalError = 2¶

InvalidArgument = 1¶

NotConnected = 6¶

NotSubscribed = 7¶

Timeout = 3¶

addresses() → str¶

Show address, model, and serial of detected controllers, where available. Detected controllers are newline-separated. Each line is comma-separated.

Available information by connection type:

Ethernet connections show address, model, and serial.
USB connections show address and model.
Serial and PCI connections show address only.

Example output:

192.168.0.40, DMC4040 Rev 1.3i, 10601
COM5, DMC-41x3
GALILPCI0

assign_ip(mac: str, ip: str) → None¶

force_gcaps(on: bool) → None¶

Force future library calls to use either gcaps or direct connections.

The default behavior of gclib is to prefer gcaps, but fall back to directoperations when gcaps is not running. This method allows disabling thedefault behavior process-wide, but cannot be undone.

Parameters:: on – If True, all future gclib calls will fail if gcaps not found, rather than falling back to direct operations. If False, gcaps will not be used for any future gclib calls.

gcaps_version() → str¶: Installed gcaps version, as reported by current gcaps server.

ip_requests() → str¶

Show MAC address, model, and serial of all controllers requesting IP addresses. Detected controllers are newline-separated. Use assign_ip() to assign an IP address to controllers returned by this method. Example output:

00:50:4c:20:29:69, DMC4000, 10601
00:50:4c:58:12:34, DMC2105, 4660

list_servers() → str¶: List available gcaps servers separated by newline.

published() → str¶: Return name of local gcaps server, or an empty string if unpublished.

server() → str¶: Current gcaps server, or an empty string if connected to the local gcaps server.

set_published(name: str = '') → None¶: Publish local gcaps server as name, or unpublish if name is empty.

set_server(name: str = '') → None¶: Use a gcaps server as reported by list_servers() for all future gcaps communications. Pass an empty string to use the local gcaps server.

version() → str¶: Version of underlying C library.