> 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/java/idevicecontrol.md).

# IDeviceControl

Create an instance of the IDeviceControl, then use the function calls described in this chapter.

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

This function closes the connection to the device.

{% code overflow="wrap" %}

```
boolean IDeviceControl.close();
```

{% endcode %}

Return Value:

Returns 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" %}

```
boolean IDeviceControl.deviceReset();
```

{% endcode %}

Return Value:

Returns true if successful. Otherwise, returns false.

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

This function sets a show message on the device’s display.

{% code overflow="wrap" %}

```
boolean IDeviceControl.displayMessage(byte messageID, byte timeout);
```

{% endcode %}

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

<table data-header-hidden><thead><tr><th width="144.45458984375" 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> </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:

Returns true if successful. Otherwise, returns false.

### 1endSession <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" %}

```
boolean IDeviceControl.endSession();
```

{% endcode %}

Return Value:

Returns 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" %}

```
boolean IDeviceControl.getInput(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="171.727294921875" 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:

Returns 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" %}

```
boolean IDeviceControl.open();
```

{% endcode %}

Return Value:

Returns 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" %}

```
boolean IDeviceControl.playSound(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="138.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">data</td><td valign="top">Byte array or string data to send to the device.</td></tr></tbody></table>

Return Value:

Returns 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 returned to the event OnEvent.

{% code overflow="wrap" %}

```
boolean IDeviceControl.send(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="176.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.</td></tr></tbody></table>

Return Value:

Returns true if successful. Otherwise, returns false.

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

This function sends a command to the device. The response will be returned to the event OnEvent.

{% code overflow="wrap" %}

```
boolean IDeviceControl.sendExtendedCommand(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="154.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.</td></tr></tbody></table>

Return Value:

Returns 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 not be returned to the event OnEvent. The response is returned as IResult which contains the StatusCode and IData.

{% code overflow="wrap" %}

```
IResult IDeviceControl.sendSync(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="141.72723388671875" 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:&#x20;

Returns IResult.

{% code overflow="wrap" %}

```
public interface IResult
{
    StatusCode Status; 
    IData Data;
}

public class Result implements IResult
{
        private StatusCode mStatus; 
        private IData mData = null;

        public Result(StatusCode status)
        {
                mStatus = status; 
                mData = null;
        }
        public Result(StatusCode status, IData data)
        {
                mStatus = status; 
                mData = null;

                if (data != null)
                        mData = data.Clone();
        }

        public StatusCode Status()
        {
                return mStatus;
        }

        public IData Data()
        {
                return mData;
        }
}

//Example Usage:
IResult result = deviceControl.sendSync(data); Log(“result = ” + result.StatusCode()); Log(“result = ” + result.Data().StringValue());
```

{% endcode %}

### 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" %}

```
boolean IDeviceControl.setDateTime(IData data);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="138.09088134765625" 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:

Returns true if successful. Otherwise, returns false.

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

This function send a command to lock or unlock the card 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" %}

```
boolean IDeviceControl.setLatch(boolean enableLock);
```

{% endcode %}

<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"><p> </p><p>enableLock</p></td><td valign="top"><p>Usage:</p><p>false – unlock the latch in the device.</p><p>true – lock the latch in the device.</p></td></tr></tbody></table>

&#x20;Return Value:

Returns true if successful. Otherwise, returns false.

### showImage <a href="#id-6.13_showimage" id="id-6.13_showimage"></a>

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

{% code overflow="wrap" %}

```
boolean IDeviceControl.showImage(byte imageID);
```

{% endcode %}

<table data-header-hidden><thead><tr><th width="157.1817626953125" 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:

Returns 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/java/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.
