> 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/ios/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 This function closes the connection to the device. {% code overflow="wrap" %} ``` (Boolean) close; ``` {% endcode %} Return Value: Returns true if successful. Otherwise, returns false. ### deviceReset 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) deviceReset; ``` {% endcode %} Return Value: Returns true if successful. Otherwise, returns false. ### displayMessage This function displays a predefined message on the device. {% code overflow="wrap" %} ``` (Boolean) displayMessage: (Byte) messageID timeout: (Byte) timeOut; (void) displayMessage: (Byte) messageID timeout: (Byte) time completionHandler: (BooleanCallback) callback; ``` {% endcode %}


Parameter	Description
messageID	Value representing the message. Usage: 0x00 - reserved, do not use. 0x01 - “AMOUNT” 0x02 - “AMOUNT OK?” 0x03 - “APPROVED” 0x04 - “CALL YOUR BANK” 0x05 - “CANCEL OR ENTER” 0x06 - “CARD ERROR” 0x07 - “DECLINED” 0x08 - “ENTER AMOUNT” 0x09 - reserved, do not use. 0x0A - reserved, do not use. 0x0B - “INSERT CARD” 0x0C – “NOT ACCEPTED” 0x0D - reserved, do not use. 0x0E - “PLEASE WAIT” 0x0F - “PROCESSING ERROR” 0x10 - “REMOVE CARD” 0x11 - “USE CHIP READER” 0x12 - “USE MAGSTRIPE” 0x13 - “TRY AGAIN” 0x14 - “WELCOME” 0x15 - “PRESENT CARD” 0x16 - “PROCESSING” 0x17 - “CARD READ OK - REMOVE CARD” 0x18 - “INSERT OR SWIPE CARD” 0x19 - “PRESENT ONE CARD ONLY” 0x1A - “APPROVED PLEASE SIGN” 0x1B - “AUTHORIZING PLEASE WAIT” 0x1C - “INSERT, SWIPE OR TRY ANOTHER CARD” 0x1D - “PLEASE INSERT CARD” 0x1E - Null prompt (empty screen) 0x1F - reserved, do not use. 0x20 - “SEE PHONE” 0x21 - “PRESENT CARD AGAIN” 0x22 - “INSERT/SWIPE/TRY OTHER CARD” 0x23 - “TAP or SWIPE CARD” 0x24 - “TAP or INSERT CARD” 0x25 - “TAP, INSERT or SWIPE CARD” 0x26 - “TAP CARD” 0x27 - “TIMEOUT” 0x28 - “TRANSACTION TERMINATED”
timeout	Timeout in seconds for the device to display the message. Usage: 0x00 - Infinite timeout. Device leaves the requested message on the display until the host initiates a change. All other values - Timeout in seconds for the device to display the message.
callback	Completion handler.

Return Value: Returns true if successful. Otherwise, returns false. ### endSession This function clears session data and returns the device to an idle state. {% code overflow="wrap" %} ``` (Boolean) endSession; ``` {% endcode %} Return Value: Returns true if successful. Otherwise, returns false. ### getInput This function sends a request for user input to the device. The response data will be returned in the event OnEvent(). {% code overflow="wrap" %} ``` (Boolean) getInput: (IData*) data; ``` {% endcode %}


Parameter	Description
data	Byte array or string data to send to the device.

Return Value: Returns true if successful. Otherwise, returns false. ### open This function opens a connection to the device. {% code overflow="wrap" %} ``` (Boolean) open; ``` {% endcode %} Return Value: Returns true if successful. Otherwise, returns false. ### playSound This function instructs the device to play a tone. {% code overflow="wrap" %} ``` (Boolean) playSound: (IData*) data; ``` {% endcode %}


Parameter	Description
data	Byte array or string data to send to the device.

Return Value: Returns true if successful. Otherwise, returns false. ### resetDeviceWithCompletionHandler 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. The response is sent to a completion handler. {% code overflow="wrap" %} ``` (void) resetDeviceWithCompletionHandler: (BooleanCallback)callback; ``` {% endcode %}


Parameter	Description
callback	Completion handler.

Return Value: None ### send This function sends a command to the device. The response will be passed to the event OnEvent(). {% code overflow="wrap" %} ``` (Boolean) send: (IData*) data; ``` {% endcode %}


Parameter	Description
data	Byte array or string data to send to the device. Data must contain the full command as required by the device.

Return Value: Returns true if successful. Otherwise, returns false. ### sendData This function sends data. {% code overflow="wrap" %} ``` (void) sendData: (IData*) data completionHandler: (BooleanCallback) callback; ``` {% endcode %}

Parameter

Description

data

Byte array or string data to send to the device. Data must contain the full command as required by the device.

callback

Completion handler. If the operation is successful, the completion handler will return true, otherwise false.

typedef void(^BooleanCallback)(Boolean resultFlag);

Return Value: None ### sendExtendedCommand {% code overflow="wrap" %} ``` sendExtendedCommand ``` {% endcode %} This function sends an extended command to the device. The response will be passed to the event OnEvent(). {% code overflow="wrap" %} ``` (Boolean) sendExtendedCommand: (IData*) data; ``` {% endcode %}


Parameter	Description
data	Byte array or string data to send to the device. Data must contain the full command as required by the device.

Return Value: Returns true if successful. Otherwise, returns false. ### sendNFCPassThroughCommand This function sends a raw APDU command from the host application to the NFC target while the device is operating in NFC Pass-Through mode. For NFC Type A or Type B using ISO 14443-4 Protocol. Used for applications that require direct APDU-level communication, such as mDL, secure element transactions, or custom NFC protocols. {% code overflow="wrap" %} ``` (Boolean) sendNFCPassThroughCommand: (IData*) data; ``` {% endcode %}


Parameter	Description
data	APDU command data to be transmitted to the NFC target device.

Return Value: Returns true if successful. Otherwise, returns false. ### sendSync This function sends a synchronous command to the device. The response from the device will be returned in IResult. {% code overflow="wrap" %} ``` (IResult*) sendSync: (IData*)data; ``` {% endcode %}


Parameter	Description
data	Byte array or string data to send to the device.

Return Value: Returns IResult\*. {% code overflow="wrap" %} ``` @interface IResult : NSObject @property (nonatomic) MTU_StatusCode status; @property (nonatomic, strong) IData* data; + (IResult*) status:(MTU_StatusCode) Status data: (IData*) Data; @end ``` {% endcode %} ### setDateTime This function sets the date and time for the device. {% code overflow="wrap" %} ``` (Boolean) setDateTime: (IData*) data; ``` {% endcode %}


Parameter	Description
data	Byte array or string data to send to the device.

Return Value: Returns true if successful. Otherwise, returns false. ### setupEADeviceProtocolString This function sets the external accessory protocol string. {% code overflow="wrap" %} ``` (void) setupEADeviceProtocolString: (NSString *)protocolString; ``` {% endcode %}


Parameter	Description
protocolString	Name of the external accessory protocol string.

Return Value: None. ### setLatch 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) setLatch: (BOOL) enableLock; ``` {% endcode %}

Parameter

Description

enableLock

Usage:

false - unlock the latch in the device.

true - lock the latch in the device.

Return Value: Returns true if successful. Otherwise, returns false. ### setLEDStatus This function controls the status of the device’s LED indicators (Light Emitting Diode) to provide visual feedback NFC operation states. Applicable after entering NFC Pass-Through mode. The status is reset after exiting NFC Pass-Through mode. {% code overflow="wrap" %} ``` (Boolean)setLEDStatus: (Byte) led status: (Byte) status; ``` {% endcode %}

Parameter

Description

led

LED number:

0x00 = LED 1 (Power LED)

0x01 = LED 2

0x02 = LED 3

0x03 = LED 4

0xFF = All 4 LEDs

Where the LEDs are numbered 1, 2, 3, 4 counting from the left.

status

LED Status:

0x00 = OFF

0x01 = GREEN ON

0x02 = RED ON

Return Value: Returns true if successful. Otherwise, returns false. ### setNFCPassThroughMode This function commands the device to enter NFC Pass-Through Mode. This enables the host application to directly exchange APDU commands and responses with an NFC card or mobile device. {% code overflow="wrap" %} ``` (Boolean) setNFCPassThroughMode: (Byte) timeout mode: (Byte) mode; ``` {% endcode %}

Parameter

Description

timeout

Duration to stay in Pass-Through mode.

0x00 = Indefinite

0x01 to 0xFF = 1 to 255 seconds

mode

Pass-Through mode.

0x00 = Stop Pass-Through Mode. Applicable only when already started. When stopped, the RF Antenna is turned off.

0x01 = Start Pass-Through Mode. This mode can only be used when the device is in Idle state.

Return Value: Returns true if successful. Otherwise, returns false. ### setNFCPollingMode This function configures the NFC reader polling behavior used to detect nearby NFC targets such as cards, mobile devices, or mDL wallets. Applicable after entering the Pass-Through mode. {% code overflow="wrap" %} ``` (Boolean) setNFCPollingMode: (Byte) timeout mode: (Byte) mode; ``` {% endcode %}

Parameter

Description

timeout

Duration to stay in Pass-Through mode.

0x00 = Indefinite

0x01 to 0xFF = 1 to 255 seconds

mode

Pass-Through mode.

0x00 = Stop Pass-Through Mode. Applicable only when already started. When stopped, the RF Antenna is turned off.

0x01 = Start Pass-Through Mode. This mode can only be used when the device is in Idle state.

Return Value: Returns true if successful. Otherwise, returns false. ### 1showBarCode This function sends a command to show a barcode on the device’s display. {% code overflow="wrap" %} ``` (Boolean) showBarCode: (BarCodeRequest*) request timeout: (Byte) timeOut prompt: (IData*) prompt; ``` {% endcode %}


Parameter	Description
request	BarCodeRequest object containing the barcode data to display.
timeout	Display Time. Usage: 0x00 = Indefinite 0x01 to 0xFF = 1 to 255 seconds
prompt	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.

#### BarCodeRequest:


Parameter	Type	Description
Type	BarCodeType	Enum to specify the type of barcode
Format	BarCodeFormat	Enum to specify the barcode format
Data	NSData*	Data to encode into a barcode
BlockColor	NSData*	Block color. Use RRGGBB format. 0x000000 = Black
BackgroundColor	NSData*	Background color. Use RRGGBB format. 0xFFFFFF = White
ErrorCorrection	Byte	Error Correction 0x00 = Low (default) 0x01 = Medium 0x02 = Quartile 0x03 = High See ISO/IEC 18004:2015
MaskPattern	Byte	Mask Pattern 0x00 to 0x07 = Mask Pattern 0xFF = Device Select Optimal Mask Pattern (default) See ISO/IEC 18004:2015
MinVersion	Byte	Minimum Version. Must be less than or equal to Maximum Version. 0x01 to 0x28 = Version 1 to Version 40 (0x01 is default) See ISO/IEC 18004:2015
MaxVersion	Byte	Maximum Version. Must be greater than or equal to Minimum Version. 0x01 to 0x28 = Version 1 to Version 40 (0x28 is default) See ISO/IEC 18004:2015

Return Value: Returns true if successful. Otherwise, returns false. ### showImage This function sends a command to immediately show an image on the device’s display. The image must already be loaded into a slot. {% code overflow="wrap" %} ``` (Boolean) showImage: (Byte) imageID; ``` {% endcode %}

Parameter

Description

imageID

Usage:

0x01 – show the image at slot 1. 0x02 – show the image at slot 2. 0x03 – show the image at slot 3. 0x04 – show the image at slot 4.

Return Value: Returns true if successful. Otherwise, returns false. ### showImage\_withCallback This function sends a command to immediately show an image on the device’s display. The image must already be loaded into a slot. The response is sent to a completion handler. {% code overflow="wrap" %} ``` (void) showImage: (Byte) imageID completionHandler: (BooleanCallback) callback; ``` {% endcode %}

Parameter

Description

imageID

Usage:

0x01 – show the image at slot 1. 0x02 – show the image at slot 2. 0x03 – show the image at slot 3. 0x04 – show the image at slot 4.

callback

Completion handler. If the operation is successful, the completion handler will return true, otherwise false.

typedef void(^BooleanCallback)(Boolean resultFlag);

Return Value: Returns true if successful. Otherwise, returns false. ### showImage\_withTimeout This function sends a command to immediately upload and show an image on the device’s display. {% code overflow="wrap" %} ``` (Boolean) showImage: (ImageData*) data timeout: (Byte) timeOut; ``` {% endcode %}

Parameter

Description

data

ImageData object containing the image to display.

timeout

Display Time Usage:

0x00 = Indefinite

0x01 to 0xFF = 1 to 255 seconds

#### ImageData


Member	Type/ Format	Description
Type	ImageType	Enum for image type. Usage: MTU_IMAGE_TYPE_BITMAP = BMP file
Data	NSData*	Image encoded data. Images must be BMP format, 160KB or smaller with no compression, maximum 320px by 240px, with color depth 16 color, 256 color, 16-bit color, or 24-bit color. Images smaller than the maximum size are centered on the display. Note images at full screen size must be 16-bit color or lower to meet the size requirement. For details see DynaFlex Family Programmer’s Manual
BackgroundColor	NSData*	Background color in RRGGBB format. 0x000000 = Black 0xFFFFFF = White

Member

Type/ Format

Description

Type

ImageType

Enum for image type. Usage:

MTU_IMAGE_TYPE_BITMAP = BMP file

Data

NSData*

Image encoded data.

Images must be BMP format, 160KB or smaller with no compression, maximum 320px by 240px, with color depth 16 color, 256 color, 16-bit color, or 24-bit color. Images smaller than the maximum size are centered on the display. Note images at full screen size must be 16-bit color or lower to meet the size requirement.

For details see DynaFlex Family Programmer’s Manual

BackgroundColor

NSData*

Background color in RRGGBB format. 0x000000 = Black

0xFFFFFF = White

Return Value: Returns true if successful. Otherwise, returns false. ### showConnectedEAAccessoryIfAny This function is to show any connected EA accessories. {% code overflow="wrap" %} ``` (void) showConnectedEAAccessoryIfAny; ``` {% endcode %} Return Value: None ### startNFCCardEmualation This function sends a command to start card emulation. * Compliance: Conforms to ISO/IEC 14443 Type-A and NFC Forum Type 4 standards. * Passive Operation mode: The NFC reader must generate the field to activate the simulated card. * Read-Only: The emulated card is read-only and does not support writing. * Supported Data Type: Supports the URI (URL) data type. {% code overflow="wrap" %} ``` (Boolean) startNFCCardEmulation: (Byte) timeOut data: (NSString*) data; ``` {% endcode %}

Parameter

Description

timeOut

Time in seconds.

0x00 = No timeout or until stopNFCCardEmulation() is called 0x01 to 0xFF = 1 to 255 seconds

data

NFC data to emulate. Limit is <= 254 characters.

Return Value: Returns true if successful. Otherwise, returns false. ### startBarCodeReader This function starts the barcode reader. The response data will be returned in the event OnEvent(). {% code overflow="wrap" %} ``` (Boolean) startBarCodeReader: (Byte) timeOut mode: (Byte) encryptionMode; ``` {% endcode %}

Parameter

Description

timeOut

Time to enable barcode reader. Usage:

0x00 = Wait until a barcode is read or stopBarCodeReader() is called. 0x01 to 0xFF = 1 to 255 seconds

encryptionMode

Encrypt payload Usage:

0x00 = do not encrypt barcode data 0x01 = encrypt barcode data.

Return Value: Returns true if successful. Otherwise, returns false. ### startPersonalInfoEntry This function sends a command to prompt a cardholder for customer information. Captured information is later returned in OnEvent() MTU\_EventType\_TouchscreenPersonalInfo. (Boolean) startPersonalInfoEntry: (MTU\_CaptureType) captureType

encrypt : (Boolean) encrypt;

Parameter

Description

captureType

Enum for the type of information to capture.

encryptionMode

Encrypt payload

false = do not encrypt data

true = encrypt data.

Return Value: Returns true if successful. Otherwise, returns false. ### 1startScan This function scans for peripherals. {% code overflow="wrap" %} ``` (void) startScan; ``` {% endcode %} Return Value: None ### startScanBarcodeWithTimeout This function starts the barcode reader. The response data will be returned in the event OnEvent(). {% code overflow="wrap" %} ``` (void) startScanBarcodeWithTimeout: (Byte) time encryptionMode: (Byte) mode completionHandler: BooleanCallback) callback; ``` {% endcode %}

Parameter

Description

time

Time to enable barcode reader. Usage:

0x00 = Wait until a barcode is read or stopBarCodeReader() is called. 0x01 to 0xFF = 1 to 255 seconds

mode

Encrypt payload Usage:

0x00 = do not encrypt barcode data 0x01 = encrypt barcode data.

callback

Completion handler. If the operation is successful, the completion handler will return true, otherwise false.

typedef void(^BooleanCallback)(Boolean resultFlag);

Return Value: None ### stopBarCodeReader 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" %} ``` (Boolean) stopBarCodeReader; ``` {% endcode %} Return Value: Returns true if successful. Otherwise, returns false. ### stopNFCCardEmualation This function sends a command to stop card emulation. {% code overflow="wrap" %} ``` (Boolean) stopNFCCardEmulation; ``` {% endcode %} Return Value: Returns true if successful. Otherwise, returns false. ### stopPersonalInfoEntry This function stops the Personal Info Entry process. If called during info entry, the process will be canceled immediately. {% code overflow="wrap" %} ``` (Boolean) stopPersonalInfoEntry; ``` {% endcode %} Return Value: Returns true if successful. Otherwise, returns false. ### stopScan This function stops the scans for peripherals. {% code overflow="wrap" %} ``` (void) stopScan; ``` {% endcode %} Return Value: None ### stopScanBarcodeWithCompletionHandler This function stops the barcode reader. {% code overflow="wrap" %} ``` (void) startScanBarcodeWithTimeout: (BooleanCallback) callback; ``` {% endcode %}

Parameter

Description

callback

Completion handler. If the operation is successful, the completion handler will return true, otherwise false.

typedef void(^BooleanCallback)(Boolean resultFlag);

Return Value: None ### turnEAAccessoryConnectionNotificationsOn This function turns on the notifications for EA accessories. {% code overflow="wrap" %} ``` (void) turnEAAccessoryConnectionNotificationsOn; ``` {% endcode %} Return Value: None ### turnEAAccessoryConnectionNotificationsOff This function turns off the notifications for EA accessories. {% code overflow="wrap" %} ``` (void) turnEAAccessoryConnectionNotificationsOff; ``` {% endcode %} Return Value: None --- # 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/ios/idevicecontrol.md?ask=&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.