Connection

evolis.Connection is the entry point for all printer communication.
It wraps the native evolis_t* context pointer from libevolis.

Constructor

Connection(printer=None, mode: OpenMode = OpenMode.AUTO)

Parameter	Type	Description
`printer`	`str` or `Device`	Printer name (OS name) or a `Device` instance. If omitted, the connection is not opened immediately.
`mode`	`OpenMode`	Communication mode. Default is `AUTO`.

Examples

# By name
co = evolis.Connection("Evolis Primacy")
 
# By Device object
devices = evolis.Evolis.get_devices()
co = evolis.Connection(devices[0])
 
# Context manager (auto-close)
with evolis.Connection("Evolis Primacy") as co:
    ...

Open / Close

Method	Signature	Description
`open`	`(name: str, mode: OpenMode = AUTO) -> bool`	Open connection by printer name.
`open_device`	`(device: Device, mode: OpenMode = AUTO) -> bool`	Open connection using a `Device` object.
`close`	`() -> None`	Close the connection. Also releases any reserved session.
`get_open_mode`	`() -> OpenMode \| None`	Returns the current communication mode.

is_open() still works but prints a deprecation warning — use get_state() instead.

State & Status

`get_state() -> State`

Returns a State object with two attributes:

state.major — State.Major enum: OFF, READY, WARNING, ERROR
state.minor — State.Minor enum (detailed sub-state, e.g. READY, DEF_NO_RIBBON, ERR_MECHANICAL)

state = co.get_state()
if state.major == evolis.State.Major.READY:
    print("Ready to print")

`get_status() -> Status | None`

Returns a Status object containing raw bit-field flags.

status = co.get_status()
if status.is_on(evolis.Status.Flag.WAR_FEEDER_EMPTY):
    print("Feeder is empty!")

`send_status_request() -> Status | None`

Sends an explicit status request command to the printer.

`enable_status() -> bool`

Enables status flags in printer replies (required on some models).

Printer Information

`get_info() -> PrinterInfo | None`

Returns a PrinterInfo object with the following fields:

Field	Type	Description
`name`	`str`	Printer name as seen by the OS
`type`	`Type`	Printer type enum
`mark`	`Mark`	Brand enum
`markName`	`str`	Brand string
`model`	`Model`	Model enum
`modelName`	`str`	Model string
`modelId`	`int`	Numeric model ID
`fwVersion`	`str`	Firmware version
`serialNumber`	`str`	Serial number
`printHeadKitNumber`	`str`	Print head kit number
`zone`	`str`	Geographic zone
`hasFlip`	`bool`	Flip-over option present
`hasEthernet`	`bool`	Ethernet option present
`hasWifi`	`bool`	WiFi option present
`hasLaminator`	`bool`	Laminator attached
`hasLaminator2`	`bool`	Second laminator attached
`hasMagEnc`	`bool`	Magnetic encoder present
`hasJisMagEnc`	`bool`	JIS magnetic encoder present
`hasSmartEnc`	`bool`	Smart card encoder present
`hasContactLessEnc`	`bool`	Contactless encoder present
`hasLcd`	`bool`	LCD screen present
`hasKineclipse`	`bool`	Kineclipse option present
`hasLock`	`bool`	Locking system present
`hasScanner`	`bool`	Scanner option present

`get_ribbon_info() -> RibbonInfo | None`

Returns ribbon details. See RibbonInfo.

`get_retransfer_film_info() -> RibbonInfo | None`

Returns retransfer film details (Avansia printers).

`get_cleaning_info() -> CleaningInfo | None`

Returns cleaning status information.

Card Movement

Method	Signature	Description
`insert_card`	`() -> bool`	Insert a card from the input tray.
`eject_card`	`() -> bool`	Eject the card to the output tray.
`reject_card`	`() -> bool`	Eject the card to the error/reject slot.
`flip_card`	`() -> bool`	Rotate the card (requires flip-over option).
`set_card_pos`	`(card_pos: CardPos) -> bool`	Move card to a specific position.

Tray Configuration

Method	Signature	Description
`get_input_tray`	`() -> InputTray \| None`	Get currently configured input tray.
`set_input_tray`	`(tray: InputTray) -> bool`	Set input tray.
`get_output_tray`	`() -> OutputTray \| None`	Get currently configured output tray.
`set_output_tray`	`(tray: OutputTray) -> bool`	Set output tray.
`get_error_tray`	`() -> OutputTray \| None`	Get the tray used for error cards.
`set_error_tray`	`(tray: OutputTray) -> bool`	Set the tray used for error cards.

Session Management

The session system prevents concurrent access to a printer.

Method	Signature	Description
`reserve`	`(session: int = 0, wait_ms: int = 5000) -> bool`	Reserve the printer. Returns `False` if busy.
`release`	`() -> bool`	Release a reserved session.
`get_session_management`	`() -> bool`	Returns `True` if session management is enabled.
`set_session_management`	`(sm: bool) -> None`	Enable/disable session management (use with caution).

Error Management

Method	Signature	Description
`get_error_management`	`() -> ErrorManagement \| None`	Get current error management mode.
`set_error_management`	`(em: ErrorManagement) -> bool`	Set error management mode (`PRINTER`, `SOFTWARE`, or `SUPERVISED`).
`clear_mechanical_errors`	`() -> bool`	Reset printer after a mechanical error.
`get_last_error`	`() -> ReturnCode`	Get last error from any method call.

Raw Communication

Method	Signature	Description
`write`	`(data, timeout_ms: int = 30000) -> bool`	Write raw bytes to printer.
`read`	`(size: int = 1024, timeout_ms: int = 30000) -> bytearray \| None`	Read raw bytes from printer.
`send_command`	`(cmd: str, reply_size: int = 1024, timeout_ms: int = 30000) -> str \| None`	Send a text command and get a text reply.

Power Management

Method	Signature	Description
`shutdown`	`() -> bool`	Shut down the printer.
`reset`	`(timeout_secs: int = 0) -> bool`	Software reset. Blocks until printer is ready.
`set_standby_time`	`(seconds: int) -> bool`	Set standby delay (0 to disable).
`get_standby_time`	`() -> int`	Get standby delay in seconds.
`set_auto_shutdown_time`	`(seconds: int) -> bool`	Set automatic shutdown delay (0 to disable).
`get_auto_shutdown_time`	`() -> int`	Get shutdown delay in seconds.

Locking System

Method	Signature	Description
`lock`	`() -> bool`	Lock the printer.
`unlock`	`() -> bool`	Unlock the printer.
`lock_enable`	`() -> bool`	Enable the electromechanical lock.
`lock_disable`	`() -> bool`	Disable the electromechanical lock.
`lock_is_enabled`	`() -> bool`	Returns `True` if the lock feature is enabled.
`get_unlock_time`	`() -> int`	Get auto-relock delay in seconds.
`set_unlock_time`	`(time: int) -> bool`	Set auto-relock delay in seconds.

Kineclipse (Security Feature)

Method	Signature	Description
`kineclipse_enable`	`() -> bool`	Enable kineclipse.
`kineclipse_disable`	`() -> bool`	Disable kineclipse.
`kineclipse_is_enabled`	`() -> bool`	Returns `True` if kineclipse is active.
`kineclipse_get_number_of_pass`	`() -> int`	Get number of kineclipse passes.
`kineclipse_set_number_of_pass`	`(passes: int) -> bool`	Set number of kineclipse passes.

BEZEL Option

Method	Signature	Description
`get_bezel_behavior`	`() -> BezelBehavior`	Get BEZEL action. Returns `EUNSUPPORTED` if no BEZEL.
`set_bezel_behavior`	`(bb: BezelBehavior) -> bool`	Set BEZEL action (re-insert / reject / nothing).
`get_bezel_delay`	`() -> int`	Get BEZEL delay in seconds.
`set_bezel_delay`	`(seconds: int) -> bool`	Set BEZEL delay.
`get_bezel_offset`	`() -> int`	Get card ejection length (mm).
`set_bezel_offset`	`(mm: int) -> bool`	Set card ejection length (17–68 mm).

Feeder (KC Max / K24)

Method	Signature	Description
`get_feeder`	`() -> Feeder`	Get selected feeder. `EUNSUPPORTED` if single feeder.
`set_feeder`	`(f: Feeder) -> bool`	Select feeder for next card insertion.

Service Events (EPS)

Method	Signature	Description
`get_event`	`() -> (str, list[ServiceAction]) \| None`	Get current EPS event name and available actions.
`set_event`	`(event_name: str, action: ServiceAction) -> bool`	Reply to an active EPS event.

Firmware Update

Method	Signature	Description
`firmware_update`	`(path: str, timeout_ms: int = 0) -> bool`	Update firmware from a file.
`firmware_update_with_buffer`	`(data, timeout_ms: int = 0) -> bool`	Update firmware from a byte buffer.

Quickstart Print Session