Retrieve a contactless UID
This guide shows how to read a contactless card's UID (the unique number returned by the chip) in eMedia Cards, store it in a database field and/or an object on the card, and print it on the card face — or store it without printing. The same steps apply on Windows and on Mac, except where this guide says otherwise.
Contactless UID retrieval is a Professional Edition feature.
Screenshots will be added later from a real UI walkthrough at FHD 1920x1080. In those pictures, the server name, user name, password and local paths will be hidden.
Before you start
You need:
-
eMedia Cards Professional Edition (Windows or Mac). If your license does not include this feature, the upgrade message below appears when you turn Contactless on or when you print.
-
A contactless reader, or a card printer with a contactless encoder. Desktop readers use the standard PC/SC interface.
-
A card template, in Design mode, with a place to store the UID: a database field, a card object (text, barcode or QR Code), or both.
-
This feature is not available on Apple Wallet templates.
Templates that already store the contactless card serial number still open and save as before. This feature reads the UID only; it does not write data onto the chip.
Step 1 - Open the Contactless dock
Work in Design mode. The dock is hidden in operating mode.
-
Click Contactless on the insert toolbar (next to Magnetic), or choose Insert > Contactless Smart Card...
-
The Contactless — UID dock opens above the card, in the same place as the magnetic encoding dock.
The toolbar button is labelled Contactless. Its tooltip is Create or edit the contents of the Contactless Smart Card.
If the license does not include the feature, a dialog titled eMedia Cards appears:
Available with Professional Edition.
Contact your reseller for a license upgrade if required.
Click OK. The dock does not open.
Screenshot (to be taken later at FHD 1920x1080; mask server, user name, password and local paths): Design mode with the insert toolbar Contactless button selected and the Contactless — UID dock open above the card.
Step 2 - Choose a reader
-
In Reader:, leave Automatic (first reader with a card) or choose a reader from the list.
-
To refresh the list, click the button to the right of Reader: (tooltip: Refresh the reader list).
With Automatic (first reader with a card), eMedia Cards prefers a contactless reader: one whose name contains CL, Contactless, PICC or NFC, or a reader that is presenting a contactless card. A reader that is listed but not plugged in appears as [name] (not connected). If the reader you chose has no card or is missing, but another slot of the same reader is presenting a contactless card, eMedia Cards reads from that slot.
If the list succeeds and no reader is connected, a warning shows: No contactless reader found. Connect a PC/SC reader, then click Refresh. If the list fails, the warning starts with Could not list contactless readers. and then the reader error.
Step 3 - Choose where to store the UID
You can store the UID in a database field, in an object on the card, or in both.
-
Store in database field: choose the field, or * None * to leave it unused.
-
Store in card object: choose a text, barcode or QR Code object, or * None to leave it unused. Objects are listed with the side they are on (Front or Back*).
Both lists refresh when you open them, so newly added fields and objects appear without closing the dock.
If neither target is set, the dock header shows Not stored. Byte order: and Base: stay disabled until you choose at least one target.
For the database field, prefer a text field. A numeric field can only hold a UID of 4 bytes or less. If the UID is longer, the message is: The UID is [length] bytes long. Database field "[name]" is numeric and holds UIDs of 4 bytes or less. Use a text field.
Step 4 - Set the byte order and base
Byte order: and Base: share one row.
-
Byte order: choose Big endian (the default) or Little endian. This is the order of the UID bytes.
-
Base: choose Hexadecimal (the default) or Decimal. This is how the UID is written in the field or object.
The collapsed dock header summarises the reader, the store target, the byte order and the base.
Step 5 - Set the card detection timeout
-
In Card detection timeout:, set how many seconds eMedia Cards waits for a card on the reader or under the antenna. The unit shown on the dock is s.
-
You can set 1 to 300. The default is 10.
This same wait is used on every path: Test read, a USB desk reader, the Evolis SDK on Windows and on Mac, a Windows Printers.ini sequence, and the Mac print queue. While the app waits, the text is a live countdown Place a card on the reader… [SECONDS] s, for example Place a card on the reader… 8 s.
Card detection timeout: is not the printer profile's Contactless insertion: setting. Contactless insertion: is only an extra delay before the read, used when a Windows printer moves the card with its profile sequence (without the SDK). It is not the time allowed for the card to be detected.
Screenshot (to be taken later at FHD 1920x1080; mask server, user name, password and local paths): the dock with a reader selected, a database field and a card object, Byte order: and Base: on one row, Card detection timeout: with the unit s, and Test read.
Step 6 - Test the read
Test read checks that the reader returns a UID. It does not write the value to the database field or to the card object.
-
Click Test read.
-
The status line first shows Place a card on the reader…, then the live countdown Place a card on the reader… [SECONDS] s, for example Place a card on the reader… 8 s. The button changes to Cancel. You can click Cancel to stop waiting; the button returns to Test read and no error is shown. If no card is presented, the wait ends after the time set in Card detection timeout:.
-
On success, the UID appears in the box next to the button, and the status line shows UID [UID] ([LENGTH] bytes) on [READER].
-
If the wait times out, the status shows No contactless card was detected on [READER] within [SECONDS] seconds. Check that the card has a contactless chip and is placed under the antenna. ([READER] is the reader name, and [SECONDS] is how long the app waited.)
If the chip returns a different UID on every read, a warning appears: This card returns a random UID at each read. It cannot be used as a card number.
Other messages you may see:
| Message | What it means |
|---|---|
| No contactless card was detected on [reader] within [n] seconds. Check that the card has a contactless chip and is placed under the antenna. | On Test read, this is the status in the dock after the wait times out. Click Test read again after placing the card. Cancel during Test read does not show this message. During print, the same text appears in the No contactless card detected dialog with Retry, Next card when the printer can move the card, and Cancel. |
| The reader is busy. Close the other program using it, then try again. | Another application has the reader open. |
| The card was removed before the UID could be read. | Keep the card on the reader until the UID appears. |
| The reader did not return the card UID | The reader could not complete the read. Try another reader, or click the refresh button and test again. |
Step 7 - Close the dock
Click the blue OK button in the dock header. The dock collapses to its title bar; Contactless stays turned on for this template. You can also use the chevron at the right of the header (Collapse contactless encoding / Expand contactless encoding).
The magnetic encoding dock has the same blue OK button (Collapse magnetic encoding).
Click Contactless on the toolbar again, or Insert > Contactless Smart Card... again, to turn the feature off for this template.
Save the template to keep the settings. The dock settings are saved with the template. Templates saved with an earlier version are repaired when you open them.
Step 8 - Print a card with the UID on the face
Switch to operating mode (the play icon on the left toolbar). Open or select the record you want to print, then choose File > Print > All..., Front side only..., Back side only..., or Card only...
On Windows, this uses the usual print dialog. On Mac, those same commands open the Print dashboard (see The Print dashboard (Mac)).
For each card, eMedia Cards:
-
Reads the UID.
-
Fills the database field and/or the card object you chose.
-
Recalculates formulas that depend on that value.
-
Prints the card face.
The UID can be read from a USB (PC/SC) reader, or from the printer's contactless antenna:
-
If Use SDK printing is on (in Tools > Options..., on the printing page) and an Evolis printer is selected, eMedia Cards uses the Evolis SDK to move the card to the antenna, then reads the UID. On Mac, choose Direct to printer (SDK) as the Print path in the Print dashboard.
-
If the SDK is not used, eMedia Cards uses the contactless commands in the printer profile to move the card to the antenna, then waits for the reader. The status line can show Moving the card to the contactless antenna… You can cancel the wait. The wait for the card uses Card detection timeout: from the dock. Contactless insertion: in the printer profile is only an extra delay before that read, not a detection timeout.
If Contactless is not turned on for the template, printing shows: Turn on Contactless for this template before printing.
While eMedia Cards waits for the card, the progress text is the live countdown Place a card on the reader… [SECONDS] s, for example Place a card on the reader… 8 s. Retry and Next card start that countdown again from the full wait.
If no contactless card is detected in time, a dialog titled No contactless card detected shows No contactless card was detected on [READER] within [SECONDS] seconds. Check that the card has a contactless chip and is placed under the antenna. The buttons are Retry, Next card, and Cancel (the same on Windows and on Mac). Retry is the default. Next card is shown only when this print path can move a card: the Evolis SDK on Windows and on Mac, and a Windows Printers.ini sequence. It is hidden on a USB desk reader and on the Mac print queue (macOS print queue).
-
Retry starts another full wait on the same reader, with the same card. You can retry as many times as you like. On a printer, the card stays at the antenna; eMedia Cards does not eject it or feed a new card.
-
Next card rejects the current card, feeds the next card from the hopper to the antenna, and reads the same record again. The record is not skipped, and the countdown restarts on that same record. After three Next card presses in a row for that record, eMedia Cards asks Three cards in a row were rejected for this record. Reject another card and feed the next one? The dialog is titled Next card, with Yes and No, so a bad stack does not empty the hopper.
-
Cancel rejects the card once (on a printer path). In a batch, you are then asked Do you want to continue printing? with Yes and No, in a dialog that still has the title No contactless card detected.
If the UID cannot be read for another reason, a dialog titled Contactless — UID shows Smart card encoder error: and the reason. When you can continue without the UID, that dialog also asks Do you want to continue printing? with Yes and No. Otherwise it has OK. On a printer, a card that was fed or moved to the antenna is rejected when the read fails.
Card rejected: the contactless UID could not be read. appears when the chosen card object is missing, or when the read fails for another reason not listed above.
Step 9 - Store the UID without printing the face
File > Print > Contactless Smart Card only... (in operating mode) does not print the card face. It does read the UID and save it to the database field you chose (when a field is set).
On Windows, this uses the usual print dialog. On Mac, it opens the same Print dashboard as a normal print (see The Print dashboard (Mac)). After you click Print, the job stores the UID only.
It reads the UID and writes the formatted value into:
-
the target object on the open template (you can undo this). Writing the UID does not mark the template as modified: a template with no unsaved changes stays that way, and a template that already had unsaved changes keeps them, and
-
the database field, when one is set. The field is saved to the database, the same way as OK on the record, and the record returns to browse with the UID showing. If the save cannot be completed, the record stays in edit with the UID filled in. A failed or cancelled read does not open the record for editing.
The same Professional Edition check applies. If the license does not include the feature, the upgrade dialog in step 1 appears and nothing is stored.
The Print dashboard (Mac)
On Mac, File > Print > All..., Front side only..., Back side only..., Card only..., and Contactless Smart Card only... all open the Print dashboard.
The window is titled Print. It has three areas:
-
Printer. Choose the printer. A line under the list may say Printer of this template, Your default printer, or macOS default printer. The printer list placeholder is Select a printer... If none are installed, the message is No printers are installed on this system. If you click Print with no printer selected, the prompt is Please select a printer. While the printer is checked, the status can show Checking printer..., then a queue status such as Ready, Paused, Offline, Error, Out of cards or feed problem, Printing, Cover open, or Status unknown. On the Direct to printer (SDK) path, the ribbon can show ~[LEFT] of [TOTAL] prints left or Ribbon: [PERCENT]% left.
-
Print path. Choose Direct to printer (SDK) or macOS print queue. With macOS print queue, the caption Bitmap only appears under the path.
-
Job. Set Resolution (for example Auto ([DPI] dpi) or [DPI] dpi), Copies, and optionally Rotate 180°. Records shows 1 (current record) for the current record, or [COUNT] records for a batch. On a double-sided card, Sides offers Front, Back, and Front + back.
The buttons are Print and Cancel. If a check appears before the job, the bar is titled Before printing [COUNT] card(s), the footer says You can still print: press Print anyway., and the button changes to Print anyway.
For Contactless Smart Card only..., the dashboard looks the same. After you click Print, eMedia Cards saves the UID to the database field (when one is set) and does not print the card face. When the UID is stored, the status line shows Contactless UID stored.
Review UID reads in the activity log
Each finished UID read adds one row to the print activity journal, on Windows and on Mac. This includes Test read and every read during print. Retry and Next card do not add rows. They are counted on the same row.
Rows are written only when Record print activity is on. Print activity reports require a Standard edition license or higher.
-
Choose Tools > Options...
-
Open the Reports category.
-
Check that Record print activity is on.
-
Read the rows under Last 50 events.
-
To show only reads that did not succeed, under Show, choose Failed and aborted only.
A contactless row shows these values:
| Column | Value |
|---|---|
| Kind | Contactless |
| Outcome | Success, No card, Read error or Cancelled |
| Record | The current database record, if one is open, then the UID, the source and the counts, separated by ·. Example: UID 04A1B2C3D4E5F6 · USB reader · Retry 1. |
Record shows UID [UID] only on success. Retry [COUNT] and Next card [COUNT] appear only when the count is above 0.
| Outcome | Meaning |
|---|---|
| Success | The UID was read. |
| No card | No card was detected within Card detection timeout:. |
| Cancelled | Cancel was clicked. |
| Read error | The read failed for another reason, for example a busy reader, a removed card or a random UID. |
| Source | Read by |
|---|---|
| USB reader | A PC/SC desk reader, including Test read. |
| Evolis SDK | An Evolis printer with Use SDK printing (Windows). |
| Printers.ini | The contactless commands from the printer profile (Windows). |
| Mac Evolis SDK | An Evolis printer on Mac. |
A contactless row has Copies 0. It does not add to the copy totals.
The UID is stored only on success. Card keys, SAM keys and the raw UID bytes are never stored.
CSV export
The CSV export adds six columns after ExtensionId. Column names are always in English.
| Column | Value |
|---|---|
| ContactlessSource | UsbReader, EvolisSdk, PrintersIni or MacEvolisSdk |
| ContactlessUid | The UID, in the Byte order: and Base: set in the dock. Empty unless the read succeeded. |
| RetryCount | Number of Retry clicks |
| NextCardCount | Number of Next card moves |
| ContactlessDetail | success, no_card, read_error or cancelled |
| ContactlessMessage | A short English reason when the read did not succeed, for example No contactless card was detected. |
On a contactless row, JobKind is Contactless, Outcome is Success, Failed or Aborted, and PrinterName holds the reader or printer name. ErrorCode gives the failure code, for example NO_CARD or READER_BUSY.
Troubleshooting
| Problem | What to do |
|---|---|
| Dialog Available with Professional Edition. | Contactless UID retrieval needs Professional Edition. Click OK, then upgrade the license, or use a Professional copy. |
| The Contactless button does nothing on an Apple Wallet template | Contactless is not available for Apple Wallet. Use a plastic-card template. |
| No contactless reader found. Connect a PC/SC reader, then click Refresh. | The list succeeded and no reader is connected. Plug in the reader, install its driver if needed, then click the refresh button next to Reader:. |
| Could not list contactless readers. | The list failed. The rest of the sentence is the reader error. Click the refresh button after the reader is connected. |
| The expected reader is missing, or shows (not connected) | Click the refresh button. If it still shows (not connected), reconnect the device. Or choose Automatic (first reader with a card). |
| The reader is busy. Close the other program using it, then try again. | Close the other application that has the reader open, then try Test read or print again. |
| An error that ends with Check the feeder or remove a card left inside. | The Evolis SDK could not feed the card or move it to the antenna. Check that cards are loaded, remove any card left inside the printer, then print again. If the printer was only busy with another job or a status check, eMedia Cards has already tried the move up to three times, one second apart. |
| Dialog Printing did not start. (Windows) | The print job could not start, for example because no printer is available for SDK printing or the printer could not be opened. Any text after the title gives the reason. Check that the printer is on and connected, and the printer settings in Tools > Options..., then print again. |
| No printer was found for direct printing. Check that the printer is connected and that its print service is running. (Mac) | On Direct to printer (SDK) in the Print dashboard, no printer was found. Connect and switch on the printer, then open the Print dashboard again. |
| Dialog No contactless card detected with Retry, Next card, and Cancel | Place a contactless card on the reader or under the printer antenna, then click Retry to wait again on the same reader, with the same card. On a printer, the card stays at the antenna. Next card, when that button is shown, rejects this card and feeds the next one for the same record. After three Next card presses in a row, eMedia Cards asks before rejecting another. Click Cancel to reject the card once; in a batch you are then asked Do you want to continue printing? Test read does not show this dialog: a timeout appears only as the status line in the dock, and Cancel on Test read does not show an error. |
| This card returns a random UID at each read. It cannot be used as a card number. | That chip does not expose a stable UID. Use a different card, or store another identifier. |
| The UID is … bytes long. Database field "…" is numeric and holds UIDs of 4 bytes or less. Use a text field. | Choose a text field in Store in database field:, or use a shorter UID with a numeric field of 4 bytes or less. |
| The serial number on the card can't be stored in the "…" field of the database as its type is not supported. | Choose a text field (or a numeric field, for a UID of 4 bytes or less). |
| Turn on Contactless for this template before printing. | In Design mode, turn Contactless on and choose a store target, then save and print from operating mode. |
| The printed face does not show the UID | Check Store in card object: points at the object you expect, and that formulas which should use the UID refer to that field or object. Run Test read first to confirm the reader. |
| A printer with an antenna never presents the card to the reader | If you use an Evolis printer with the SDK, check Use SDK printing in Tools > Options.... If you do not use the SDK, eMedia Cards still moves the card with the contactless commands from the printer profile, then waits for the reader for the time set in Card detection timeout:. Contactless insertion: in the printer profile is only an extra delay before that read. Check the cable, the printer, and the Contactless encoding log on Windows. |
Diagnostic log (Windows)
To capture a contactless UID trace for support:
-
Choose Tools > Options...
-
Open the Logs category.
-
Under the Print group, turn on Contactless encoding.
The description on that option is: UID read, reader choice, and Printers.ini contactless sequences (contactlessencoding.log). Card keys are never written.
The file is contactlessencoding.log, in the logs folder you can open with Open logs folder on the same page. The log may include the UID. It never includes card keys or SAM keys.
When a print wait times out, each Retry adds a line such as Timeout retry reader=... attempt=N (the reader name and the attempt number). Each Next card adds Timeout next card reader=... attempt=N. Cancel adds the line Timeout cancelled.
On Mac there is no Logs page. The same contactless lines are written to contactlessencoding.log under the app settings folder (~/Library/Application Support/Mediasoft/eMedia Cards/logs, or the debug test-state settings folder). Command warnings go to command.log in that same folder. Card keys are not written. A UID may be.