> For the complete documentation index, see [llms.txt](https://developer.magtek.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.magtek.com/sdks-and-tools/universal-sdk-documentation/linux/idevicecontrol.md).

# IDeviceControl

Create an instance of the IDeviceControl using IDevice getDeviceControl. Then use the function calls described in this chapter.

Generally, these functions will run in one of two modes:

* Asynchronous functions return data in the event handlers.
* Synchronous functions return data in the return value. If the data is not available immediately, the call will block until a wait time has elapsed.

## close <a href="#id-6.1_close" id="id-6.1_close"></a>

This function closes the connection to the device.

{% code overflow="wrap" %}

```
bool IDeviceControl->close();
```

{% endcode %}

Return Value: True if successful. Otherwise, returns false.

## deviceReset <a href="#id-6.2_devicereset" id="id-6.2_devicereset"></a>

This function resets the device. This is equivalent to a power reset. After the reset, connection to the device will need to be re-established.

{% code overflow="wrap" %}

```
bool IDeviceControl->deviceReset();
```

{% endcode %}

Return Value: True if successful. Otherwise, returns false.

## displayMessage <a href="#id-6.3_displaymessage" id="id-6.3_displaymessage"></a>

This function displays a predefined message on the device.

{% code overflow="wrap" %}

```
bool IDeviceControl->displayMessage( unsigned char messageID, unsigned char timeout);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="129" valign="top">Parameter</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p> </p><p>messageID</p></td><td valign="top"><p>Value representing the message.</p><p> </p><p>Usage:</p><ul><li>0x00 - reserved, do not use. </li><li>0x01 - “AMOUNT”</li><li>0x02 - “AMOUNT OK?”</li><li>0x03 - “APPROVED”</li><li>0x04 - “CALL YOUR BANK”</li><li>0x05 - “CANCEL OR ENTER”</li><li>0x06 - “CARD ERROR”</li><li>0x07 - “DECLINED”</li><li>0x08 - “ENTER AMOUNT”</li><li>0x09 - reserved, do not use. 0x0A - reserved, do not use. </li><li>0x0B - “INSERT CARD”</li><li>0x0C – “NOT ACCEPTED”</li><li>0x0D - reserved, do not use. 0x0E - “PLEASE WAIT”</li><li>0x0F - “PROCESSING ERROR”</li><li>0x10 - “REMOVE CARD”</li><li>0x11 - “USE CHIP READER”</li><li>0x12 - “USE MAGSTRIPE”</li><li>0x13 - “TRY AGAIN”</li><li>0x14 - “WELCOME”</li><li>0x15 - “PRESENT CARD”</li><li>0x16 - “PROCESSING”</li><li>0x17 - “CARD READ OK - REMOVE CARD”</li><li>0x18 - “INSERT OR SWIPE CARD”</li><li>0x19 - “PRESENT ONE CARD ONLY”</li><li>0x1A - “APPROVED PLEASE SIGN”</li><li>0x1B - “AUTHORIZING PLEASE WAIT”</li><li>0x1C - “INSERT, SWIPE OR TRY ANOTHER CARD”</li><li>0x1D - “PLEASE INSERT CARD”</li><li>0x1E - Null prompt (empty screen) 0x1F - reserved, do not use.</li><li>0x20 - “SEE PHONE”</li><li>0x21 - “PRESENT CARD AGAIN”</li><li>0x22 - “INSERT/SWIPE/TRY OTHER CARD”</li><li>0x23 - “TAP or SWIPE CARD”</li><li>0x24 - “TAP or INSERT CARD”</li><li>0x25 - “TAP, INSERT or SWIPE CARD”</li><li>0x26 - “TAP CARD”</li><li>0x27 - “TIMEOUT”</li><li>0x28 - “TRANSACTION TERMINATED”</li><li>0x29 - “USE CHIP READER or MAGSTRIPE”</li><li>0x2A - “SCAN BARCODE”</li><li>0x2B - “BARCODE READ SUCCESSFULLY”</li><li>0x2C - “CANCELED”</li><li>0x2D - “SWIPE CARD or SCAN BARCODE”</li><li>0x2E - “INSERT CARD or SCAN BARCODE”0x2F - “INSERT, SWIPE or SCAN BARCODE”</li></ul></td></tr></tbody></table>

<table data-header-hidden><thead><tr><th width="125.3636474609375" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top"> </td><td valign="top"><ul><li>0x30 - “TAP CARD or SCAN BARCODE”</li><li>0x31 - “TAP, SWIPE or SCAN BARCODE”</li><li>0x32 - “TAP, INSERT or SCAN BARCODE”</li><li>0x33 - “TAP, INSERT, SWIPE or SCAN BARCODE”</li><li>0x34 - “TRY ANOTHER INTERFACE”</li><li>0x35 - “NFC TAG DETECTED”</li><li>0x36 - “ERROR REMOVE CARD”</li><li>0x37 - “MIFARE CLASSIC 1K DETECTED”</li><li>0x38 - “MIFARE CLASSIC 4K DETECTED”</li><li>0x39 - “MIFARE DESFIRE DETECTED”</li></ul></td></tr><tr><td valign="top"><p> </p><p> </p><p> </p><p>timeout</p></td><td valign="top"><p>Timeout in seconds for the device to display the message.</p><p> </p><p>Usage:</p><p>0x00 - Infinite timeout. Device leaves the requested message on the display until the host initiates a change.</p><p> </p><p>All other values - Timeout in seconds for the device to display the message.</p></td></tr></tbody></table>

Return Value: True if successful. Otherwise, returns false.

## endSession <a href="#id-6.4_endsession" id="id-6.4_endsession"></a>

This function clears session data and returns the device to an idle state.

{% code overflow="wrap" %}

```
bool IDeviceControl->endSession();
```

{% endcode %}

Return Value: True if successful. Otherwise, returns false.

## getInput <a href="#id-6.5_getinput" id="id-6.5_getinput"></a>

This function sends a request for user input at the device. The response data will be returned in the event OnEvent().

{% code overflow="wrap" %}

```
bool IDeviceControl->getInput(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="149.9090576171875" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top">data</td><td valign="top">Byte array or string data to send to the device.</td></tr></tbody></table>

Return Value: True if successful. Otherwise, returns false.

## open <a href="#id-6.6_open" id="id-6.6_open"></a>

This function opens a connection to the device.

{% code overflow="wrap" %}

```
bool IDeviceControl->open();
```

{% endcode %}

Return Value: True if successful. Otherwise, returns false.

## playSound <a href="#id-6.7_playsound" id="id-6.7_playsound"></a>

This function instructs the device to play a tone.

{% code overflow="wrap" %}

```
bool IDeviceControl->playSound(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="146.272705078125" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top">data</td><td valign="top">Byte array or string data to send to the device.</td></tr></tbody></table>

Return Value: True if successful. Otherwise, returns false.

## send <a href="#id-6.8_send" id="id-6.8_send"></a>

This function sends a command to the device. The response will be passed to the event OnEvent().

{% code overflow="wrap" %}

```
bool IDeviceControl->send(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="124.45452880859375" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top">data</td><td valign="top">Byte array or string data to send to the device. Data must contain the full command as required by the device.</td></tr></tbody></table>

Return Value: True if successful. Otherwise, returns false.

## sendExtendedCommand <a href="#id-6.9_sendextendedcommand" id="id-6.9_sendextendedcommand"></a>

This function sends an extended command to the device. The response will be passed to the event OnEvent().

{% code overflow="wrap" %}

```
bool IDeviceControl->sendExtendedCommand(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="116.27276611328125" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top">data</td><td valign="top">Byte array or string data to send to the device. Data must contain the full command as required by the device.</td></tr></tbody></table>

Return Value: True if successful. Otherwise, returns false.

## sendSync <a href="#id-6.10_sendsync" id="id-6.10_sendsync"></a>

This function sends a synchronous command to the device. The response from the device will be returned in IResult.

{% code overflow="wrap" %}

```
IResult IDeviceControl->sendSync(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top">data</td><td valign="top">Byte array or string data to send to the device.</td></tr></tbody></table>

Return Value: IResult.

## setDateTime <a href="#id-6.11_setdatetime" id="id-6.11_setdatetime"></a>

This function sets the date and time for the device.

{% code overflow="wrap" %}

```
bool IDeviceControl->setDateTime(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="163.5455322265625" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top">data</td><td valign="top">Byte array or string data to send to the device.</td></tr></tbody></table>

Return Value: True if successful. Otherwise, returns false.

## setLatch <a href="#id-6.12_setlatch" id="id-6.12_setlatch"></a>

This function is to lock or unlock the card latch. Applicable on devices equipped with a latch. The host can choose to lock the card during EMV transactions to limit the possibility of the cardholder prematurely removing the card. The lock can also be enabled while the card is out of the system to block cardholders from inserting a card.

{% code overflow="wrap" %}

```
bool IDeviceControl->setLatch(bool enableLock);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="156.27276611328125" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top"><p> </p><p>enableLock</p></td><td valign="top"><p>Usage:</p><ul><li>false - unlock the latch in the device.</li><li>true - lock the latch in the device.</li></ul></td></tr></tbody></table>

Return Value: True if successful. Otherwise, returns false.

## showBarCode <a href="#id-6.13_showbarcode" id="id-6.13_showbarcode"></a>

This function sends a command to show a barcode on the device’s display.

{% code overflow="wrap" %}

```
bool IDeviceControl->showBarCode( BarCodeRequest data unsigned char timeout IData* prompt = NULL);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="133.54547119140625" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top">data</td><td valign="top">BarCodeRequest object containing the barcode data to display.</td></tr><tr><td valign="top"><p> </p><p>timeout</p></td><td valign="top"><p>Display Time. Usage:</p><ul><li>0x00 = Indefinite</li><li>0x01 to 0xFF = 1 to 255 seconds</li></ul></td></tr><tr><td valign="top"><p> </p><p>prompt</p></td><td valign="top">Text to display below the QR code. In Landscape orientation, the limit is approximately 30 characters. In Portrait orientation, the limit is approximately 22 characters.</td></tr></tbody></table>

## **BarCodeRequest**

<table data-header-hidden><thead><tr><th width="112.9090576171875" valign="top"></th><th width="210.1817626953125" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Type</td><td valign="top">Description</td></tr><tr><td valign="top">Type</td><td valign="top">BarCodeType</td><td valign="top">Enum to specify the type of barcode</td></tr><tr><td valign="top">Format</td><td valign="top">BarCodeFormat</td><td valign="top">Enum to specify the barcode format</td></tr><tr><td valign="top">Data</td><td valign="top">vector&#x3C;unsigned char></td><td valign="top">Data to encode into a barcode</td></tr></tbody></table>

<table data-header-hidden><thead><tr><th width="160.18182373046875" valign="top"></th><th width="222.5455322265625" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Type</td><td valign="top">Description</td></tr><tr><td valign="top">BlockColor</td><td valign="top">vector&#x3C;unsigned char></td><td valign="top"><p>Block color. Use RRGGBB format. </p><ul><li>0x000000 = Black</li></ul></td></tr><tr><td valign="top">BackgroundColor</td><td valign="top">vector&#x3C;unsigned char></td><td valign="top"><p>Background color. Use RRGGBB format.</p><ul><li>0xFFFFFF = White</li></ul></td></tr><tr><td valign="top">ErrorCorrection</td><td valign="top">unsigned char</td><td valign="top"><p>Error Correction </p><ul><li>0x00 = Low (default) </li><li>0x01 = Medium </li><li>0x02 = Quartile </li><li>0x03 = High</li></ul><p>See ISO/IEC 18004:2015</p></td></tr><tr><td valign="top">MaskPattern</td><td valign="top">unsigned char</td><td valign="top"><p>Mask Pattern</p><ul><li>0x00 to 0x07 = Mask Pattern</li><li>0xFF = Device Select Optimal Mask Pattern (default) </li></ul><p>See ISO/IEC 18004:2015</p></td></tr><tr><td valign="top">MinVersion</td><td valign="top">unsigned char</td><td valign="top"><p>Minimum Version. Must be less than or equal to Maximum Version. </p><ul><li>0x01 to 0x28 = Version 1 to Version 40 (0x01 is default)</li></ul><p>See ISO/IEC 18004:2015</p></td></tr><tr><td valign="top">MaxVersion</td><td valign="top">unsigned char</td><td valign="top"><p>Maximum Version. Must be greater than or equal to Minimum Version.</p><ul><li>0x01 to 0x28 = Version 1 to Version 40 (0x28 is default) </li></ul><p>See ISO/IEC 18004:2015</p></td></tr></tbody></table>

Return Value: True if successful. Otherwise, returns false.

## showImage - no upload <a href="#id-6.14_showimage" id="id-6.14_showimage"></a>

This function sends a command to immediately show an image on the device’s display. The image must already be loaded into a slot by sendImage().

{% code overflow="wrap" %}

```
bool IDeviceControl->showImage(unsigned char imageID);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="118.09100341796875" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top"><p> </p><p> </p><p>imageID</p></td><td valign="top"><p>Usage:</p><ul><li>0x01 – show the image at slot 1. </li><li>0x02 – show the image at slot 2. </li><li>0x03 – show the image at slot 3. </li><li>0x04 – show the image at slot 4.</li></ul></td></tr></tbody></table>

Return Value: True if successful. Otherwise, returns false.

## showImage - with upload <a href="#id-6.15_showimage" id="id-6.15_showimage"></a>

This function sends a command to immediately upload and show an image on the device’s display.

{% code overflow="wrap" %}

```
bool IDeviceControl->showImage(
    ImageData data
    unsigned char timeout);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="113.5455322265625" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top">data</td><td valign="top">ImageData object containing the image to display.</td></tr><tr><td valign="top"><p> </p><p>timeout</p></td><td valign="top"><p>Display Time Usage:</p><ul><li>0x00 = Indefinite</li><li>0x01 to 0xFF = 1 to 255 seconds</li></ul></td></tr></tbody></table>

## **ImageData**

<table data-header-hidden><thead><tr><th width="159.272705078125" valign="top"></th><th width="209.9090576171875" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Member</td><td valign="top">Type/ Format</td><td valign="top">Description</td></tr><tr><td valign="top"><p> </p><p>type</p></td><td valign="top"><p> </p><p>ImageType</p></td><td valign="top"><p>Enum for image type. Usage:</p><p>IMAGE_TYPE_BITMAP = BMP file</p></td></tr><tr><td valign="top">data</td><td valign="top">vector&#x3C;unsigned char></td><td valign="top">Image encoded data.</td></tr><tr><td valign="top"><p> </p><p>backgroundColor</p></td><td valign="top"><p> </p><p>vector&#x3C;unsigned char></p></td><td valign="top"><p>Background color in RRGGBB format. </p><ul><li>0x000000 = Black</li><li>0xFFFFFF = White</li></ul></td></tr></tbody></table>

Return Value: True if successful. Otherwise, returns false.

## startBarCodeReader <a href="#id-6.16_startbarcodereader" id="id-6.16_startbarcodereader"></a>

This function sends a command to start the barcode reader.

{% code overflow="wrap" %}

```
bool IDeviceControl->startBarCodeReader( 
    unsigned char timeout
    unsigned char encryptionMode);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="159.90911865234375" valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Parameter</td><td valign="top">Description</td></tr><tr><td valign="top"><p> </p><p>timeout</p></td><td valign="top"><p>Time to enable barcode reader. Usage:</p><ul><li>0x00 = Wait until a barcode is read or stopBarCodeReader() is called.</li><li>0x01 to 0xFF = 1 to 255 seconds</li></ul></td></tr><tr><td valign="top"><p> </p><p>encryptionMode</p></td><td valign="top"><p>Encrypt payload Usage:</p><ul><li>0x00 = do not encrypt barcode data </li><li>0x01 = encrypt barcode data.</li></ul></td></tr></tbody></table>

Return Value: True if successful. Otherwise, returns false.

## stopBarCodeReader <a href="#id-6.17_stopbarcodereader" id="id-6.17_stopbarcodereader"></a>

This function sends a command to stop the barcode reader. This is applicable only when the timeout value for startBarCodeReader() was set to 0x00.

{% code overflow="wrap" %}

```
bool IDeviceControl->stopBarCodeReader();
```

{% endcode %}

Returns Value: True if successful. Otherwise, returns false.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.magtek.com/sdks-and-tools/universal-sdk-documentation/linux/idevicecontrol.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
