Printing Black Content to the Card Front — Complete Example

This guide shows how to print black-only content to the front face of a card using the Evolis Primacy printer.

How Black Printing Works

The Evolis Primacy uses a YMCKO ribbon (Yellow, Magenta, Cyan, Black resin, Overlay).
The K (black resin) panel delivers sharp, high-contrast black text and barcodes.

There are two ways to print black:

Method	When to use
`set_black()`	You have a 1bpp monochrome BMP; uses K panel only
`set_image()`	Full-color BMP; the SDK converts black pixels automatically

Image Requirements

Method	Format	Bit depth
`set_image`	BMP	24-bit color
`set_black`	BMP	1 bit per pixel (monochrome)

A standard 24-bit black BMP will work with set_image(). For set_black(), you must convert the image to 1bpp first (see below).

Example 1 — Full-Color Image (Simplest)

import evolis
 
PRINTER_NAME = "Evolis Primacy"   # adjust to match your printer name
 
with evolis.Connection(PRINTER_NAME) as co:
    state = co.get_state()
    if state.major != evolis.State.Major.READY:
        print("Printer not ready:", state.minor)
        exit(1)
 
    ps = evolis.PrintSession(co)
    ps.set_image(evolis.CardFace.FRONT, "/path/to/front_color.bmp")
 
    rc = ps.print()
    if rc == evolis.ReturnCode.OK:
        print("Print successful")
    else:
        print("Print failed:", rc, "| last error:", ps.get_last_error())

Example 2 — Black Panel Only (K resin, from file)

import evolis
 
PRINTER_NAME = "Evolis Primacy"
 
with evolis.Connection(PRINTER_NAME) as co:
    state = co.get_state()
    if state.major != evolis.State.Major.READY:
        print("Printer not ready:", state.minor)
        exit(1)
 
    ps = evolis.PrintSession(co)
 
    # 1bpp monochrome BMP — black pixels print with K panel
    ps.set_black(evolis.CardFace.FRONT, "/path/to/black_front_1bpp.bmp")
 
    rc = ps.print()
    if rc == evolis.ReturnCode.OK:
        print("Black print successful")
    else:
        print("Print failed:", rc)

Example 3 — Plug-and-play self-contained script

See print_black_example.py — a single file you can run directly:

pip install Evolis-SDK Pillow
python print_black_example.py                    # auto-discovers first printer
python print_black_example.py "Evolis Primacy"   # explicit printer name

The script:

Generates a full CR-80 card design (1013×638 px, 1bpp BMP) entirely in memory — no external image files needed
Discovers the printer automatically if no name is given
Checks printer state and clears mechanical errors if needed
Prints using the K (black resin) panel only
Reports success or the exact error code

Core of the generation:

from PIL import Image, ImageDraw
import io
 
W, H = 1013, 638  # CR-80 at 300 DPI
 
img = Image.new("RGB", (W, H), color=(255, 255, 255))
draw = ImageDraw.Draw(img)
 
draw.rectangle([0, 0, W, 80], fill=(0, 0, 0))           # top bar
draw.text((30, 20), "EVOLIS PRIMACY", fill=(255, 255, 255))
draw.text((50, 120), "Name:   John Smith", fill=(0, 0, 0))
# ... more drawing ...
 
img_1bpp = img.convert("1")      # convert to 1 bit per pixel
buf = io.BytesIO()
img_1bpp.save(buf, format="BMP")
bmp_bytes = bytearray(buf.getvalue())

Example 4 — Color + Black overlay (YMCKO ribbon)

For the Primacy you can combine the color YMC panels with the K panel in the same job:

import evolis
 
with evolis.Connection("Evolis Primacy") as co:
    ps = evolis.PrintSession(co)
 
    # Background photo on YMC panels (24bpp)
    ps.set_image(evolis.CardFace.FRONT, "/path/to/background.bmp")
 
    # Sharp black text/barcode on K panel (1bpp)
    ps.set_black(evolis.CardFace.FRONT, "/path/to/black_overlay.bmp")
 
    rc = ps.print()
    print("Result:", rc)

Selecting Your Ribbon Explicitly (faster init)

ps = evolis.PrintSession(co, evolis.RibbonType.YMCKO)

This skips the printer query and is faster. Make sure the physical ribbon matches.

For a K-black-only ribbon:

ps = evolis.PrintSession(co, evolis.RibbonType.KBLACK)
ps.set_black(evolis.CardFace.FRONT, "/path/to/black_front.bmp")

Troubleshooting

Return Code	Meaning	Fix
`PRINT_NEEDACTION`	Printer not ready (ribbon, cover, feeder)	Check printer state/status flags
`PRINT_EDATA`	Invalid image data	Verify BMP format and bit depth
`PRINT_ENOIMAGE`	No image set	Call `set_image()` or `set_black()` before `print()`
`PRINT_EMECHANICAL`	Mechanical jam	Call `co.clear_mechanical_errors()`
`PRINT_EUNKNOWNRIBBON`	Ribbon type not set	Pass `RibbonType` to constructor or set `GRibbonType` setting
`PRINTER_ENOCOM`	Printer offline	Check USB/network connection

# After a mechanical error
co.clear_mechanical_errors()

Printer Name Discovery

import evolis
 
devices = evolis.Evolis.get_devices()
for d in devices:
    print(d.name)   # use this string in Connection(...)

Print Session Setting Keys