Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Page cover
ChatGPT

Application Group 0x01 - General Messages

Command 0x01::0x02 - Clear Transaction Data

The host uses this command to direct the device to clear all transaction data, including account data, encrypted PIN block, PAN, and amount, and return to the idle state.

Table - Message Structure for Command 0x01::0x02 - Clear Transaction Data

Tag

Len

Value(s) / Description

C0

01

01

Message Type Data Object (Tag C0) = 0x01 Command

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

02

Command ID Data Object (Tag C2) = 0x02 Clear Transaction Data

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Table - Response to Command 0x01::0x02 - Clear Transaction Data

Tag

Len

Value(s) / Description

C0

01

02

Message Type Data Object (Tag C0) = 0x02 Response

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

02

Command ID Data Object (Tag C2) = 0x02 Clear Transaction Data

C3

01

00

Result Code Data Object (Tag C3) = OK / Done

Command 0x01::0xFF - Device Reset

The host uses this command to direct the device to reset.

Table - Message Structure for Command 0x01::0xFF - Device Reset

Tag

Len

Value(s) / Description

C0

01

01

Message Type Data Object (Tag C0) = 0x01 Command

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

FF

Command ID Data Object (Tag C2) = 0xFF Device Reset

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Table - Response to Command 0x01::0xFF - Device Reset

Tag

Len

Value(s) / Description

C0

01

02

Message Type Data Object (Tag C0) = 0x02 Response

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

FF

Command ID Data Object (Tag C2) = 0xFF Device Reset

C3

01

00

Result Code Data Object (Tag C3) = OK / Done

Notification 0x01::0xFF - Device Reset

The device sends this notification to the host to notify the host that it is about to perform a periodic automatic device reset, which it initiates after 23 hours of continuous operation to fulfill PCI requirements. MagTek recommends the host software pre-empt these automatic resets by initiating resets in advance of the 23 hour schedule, at times that are least disruptive to the solution design.

Table - Response to Notification 0x01::0xFF - Device Reset

Tag

Len

Value(s) / Description

C0

01

03

Message Type Data Object (Tag C0) = 0x03 Notification

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

FF

Command ID Data Object (Tag C2) = 0xFF Device Reset

Command 0x01::0x04 - Get Device Status

The host uses this command to request the device status, such as Session State, Device State, and Status.

Table - Message Structure for Command 0x01::0x04 - Get Device Status

Tag

Len

Value(s) / Description

C0

01

01

Message Type Data Object (Tag C0) = 0x01 Command

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

04

Command ID Data Object (Tag C2) = 0x04 Get Device Status

If an error occurs, the device will terminate the command and report the error using an ACK Response containing the result code. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3). If no error occurs, the device responds as follows:

Table - Response to Command 0x01::0x04 - Get Device Status

Tag

Len

Value(s) / Description

C0

01

02

Message Type Data Object (Tag C0) = 0x02 Response

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

04

Command ID Data Object (Tag C2) = 0x04 Get Device Status

C3

01

00

Result Code Data Object (Tag C3) = OK / Done

E0

Calculated

Data Field Data Object (Tag C4 or E0) =

Data Object F1 - Device Status

Notification 0x01::0x04 - Send Device Status

In addition to sending device status in response to Command 0x01::0x04 - Get Device Status, the device will automatically send the same data when the device powers up, restarts, or changes state.

Table - Message Structure for Notification 0x01::0x04 - Send Device Status

Tag

Len

Value(s) / Description

C0

01

03

Message Type Data Object (Tag C0) = 0x03 Notification

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

04

Command ID Data Object (Tag C2) = 0x04 Get Device Status

C3

01

00

Result Code Data Object (Tag C3) = OK / Done

E0

Calculated

Data Field Data Object (Tag C4 or E0) =

Data Object F1 - Device Status

Command 0x01::0x10 - Send Big Block Command

The host uses this command to send command messages to the device as a sequence of packets. The host should follow this sequence:

  • In local memory, compose the entire command message as documented by the desired command’s usage table (for example, Command 0x01::0x17 - Update Firmware).

  • Calculate the length of the fully-composed command message. Divide the fully-composed command message into packets that are shorter than the connection type’s maximum packet size.

    • When using the USB connection, the maximum packet size is 0x3F bytes.

    • When using the Ethernet connection, the maximum packet size is 0x0400 bytes.

    • When using a serial connection, the maximum packet size is 0x0400 bytes.

  • Send command 0x01::0x10 to the device as “Packet 0.” Packet 0 is short and sets up how much data the device should expect across the whole big block operation. The C4 data object can be of varying length, and its value should be a 2-byte Packet Number equal to 00 00, plus a 2-byte Packet Length, plus Packet Data containing the Total Command Message Length, in bytes, the device should expect to receive when concatenating all subsequent packets (see Table 4-29).

  • Wait to receive a response from the device (see Table 4-31).

  • Continue sending Command 0x01::0x10 to send Packets 1 through n, incrementing the Packet Number by 1 each time, until the host has sent the fully-composed command message. After sending each packet, wait for the device’s response to reduce risk of packets arriving out of order. The C4 data object for packets 1 through n can be of varying length, and its value should be a 2-byte Packet Number that increments with each call to this command, plus a 2-byte Packet Data Length, plus the Packet Data (see Table 4-30).

  • Listen for a final response from the device acknowledging the completed command. This means after sending the final packet, the host should expect to receive two responses: One for the final packet sent with Command 0x01::0x10, and one after the device has finished processing all the uploaded data and responds to the fully-composed command message the host has sent (for example, Command 0x01::0x17 - Update Firmware).

Table - Message Structure for Command 0x01::0x10 - Send Big Block Command (Packet 0 Only)

Tag

Len

Value(s) / Description

C0

01

01

Message Type Data Object (Tag C0) = 0x01 Command

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

10

Command ID Data Object (Tag C2) = 0x10 Send Big Block Command Message

C4

Calculated

Data Field Data Object (Tag C4 or E0) = 2-byte Packet Number = 00 00

2-byte Packet Data Length, LSB first

Packet Data = Total Command Message Length in bytes the device is sending using big block packets, LSB first

Table - Message Structure for Command 0x01::0x10 - Send Big Block Command (Packets 1 through n)

Tag

Len

Value(s) / Description

C0

01

01

Message Type Data Object (Tag C0) = 0x01 Command

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

10

Command ID Data Object (Tag C2) = 0x10 Send Big Block Command Message

C4

Calculated

Data Field Data Object (Tag C4 or E0) = 2-byte Packet Number, LSB first

2-byte Packet Data Length, LSB first Packet Data, LSB first

For every packet the host sends, if an error occurs (such as an out of order packet), the device will terminate the command, report the error using an ACK Response containing the result code, and will stop expecting to receive subsequent big block packets. The host should stop sending them. For a full list of error codes, see 2.4.4 Result Code Data Object (Tag C3).

If no error occurs, the device responds to every packet as follows:

Table - Response to Command 0x01::0x10 - Send Big Block Command

Tag

Len

Value(s) / Description

C0

01

02

Message Type Data Object (Tag C0) = 0x02 Response

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

10

Command ID Data Object (Tag C2) = 0x10 Send Big Block Command Message

C3

01

00

Result Code Data Object (Tag C3) = OK / Done

Notification 0x01::0x10 - Big Block Device Data

The device uses this notification to send data to the host as a sequence of packets. The host should process this notification as follows:

  • The host may receive this notification completely unsolicited or in response to a command (all commands that operate in this way say so in the command documentation). If the host has sent such a command to the device, it should start a timeout counter and begin listening for incoming notifications.

  • Parse the first incoming notification, which should be identified as Packet 0000, according to Table 4-32 below. Use the value of Total Message Length to allocate buffer space to begin concatenating all subsequent packets, which together form the complete message.

  • Continue receiving packets 0001 through nnnn, parsing them according to Table 4-33 below, concatenating the Packet Data from all notifications in order and adding the length of Packet Data in each packet, until the length of concatenated message data equals the Total Message Length.

  • If the complete message is a notification type, the host should parse it according to the notification’s documentation. If it is a response type, the host should parse it according to the corresponding command’s response table.

Table - Message Structure for Notification 0x01::0x10 - Big Block Device Data (Packet 0 Only)

Tag

Len

Value(s) / Description

C0

01

01

Message Type Data Object (Tag C0) = 0x03 Notification

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

10

Command ID Data Object (Tag C2) = 0x10 Big Block Device Data

C4

08

Data Field Data Object (Tag C4 or E0) = 2-byte Packet Number = 00 00

2-byte Packet Data Length, LSB first

4-byte Total Message Length in bytes, LSB first

Table - Message Structure for Notification 0x01::0x10 - Big Block Device Data (Packets 1 through n)

Tag

Len

Value(s) / Description

C0

01

03

Message Type Data Object (Tag C0) = 0x03 Notification

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

10

Command ID Data Object (Tag C2) = 0x10 Big Block Device Data

C4

Calculated

Data Field Data Object (Tag C4 or E0) = 2-byte Packet Number, LSB first

2-byte Packet Data Length, LSB first Packet Data

Command 0x01::0x17 - Update Firmware

The host uses this command to update the device’s firmware. The host should first compose the entire message for this command, then transmit the entire message to the device in packets using Command 0x01::0x10 - Send Big Block Command.

Table - Message Structure for Command 0x01::0x17 - Update Firmware

Tag

Len

Value(s) / Description

C0

01

01

Message Type Data Object (Tag C0) = 0x01 Command

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

17

Command ID Data Object (Tag C2) = 0x17 Update Firmware

C4

Calculated

Data Field Data Object (Tag C4 or E0) = Byte 1 Subcommand

0x01 = Update boot loader 0x02 = Reserved

0x03 = Update firmware image 0x04 = Reserved

Bytes 2..n: Firmware image binary data

After the device receives the final packet of this command, the device will validate the firmware image, and if the validation passes, it will commit the image to the selected firmware storage location. In all cases, the device will also send an additional response:

Table - Response to Command 0x01::0x17 - Update Firmware

Tag

Len

Value(s) / Description

C0

01

02

Message Type Data Object (Tag C0) = 0x02 Response

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

17

Command ID Data Object (Tag C2) = 0x17 Update Firmware

C3

01

Result Code Data Object (Tag C3): 0x00 = Update successful

0x01 = Invalid firmware image loaded in buffer 0x02 = Signature error

0x03 = Build version error 0x09 = Other error

Although this command works on all connection types, for speed reasons, MagTek recommends using an

Ethernet or USB connection to upgrade the device’s firmware.

Notification 0x01::0x40 - Card Detected / Identified / Removed

The device uses this notification to signal to the host that a cardholder has inserted or removed a card, and to identify the type of card. Upon insertion or removal of a card, the device sends this notification to provide a Card Present Indication (CPI). After the device finishes identifying the type of card, it sends this notification again to provide an ICC Present Indication (IPI). When the CPI indicates a card is present and the IPI reports it is a chip card, the host is free to begin an EMV transaction, or in the case of magnetic stripe cards, to prompt the cardholder to remove the card to swipe on exit.

Table - Message Structure for Notification 0x01::0x40 - Card Detected / Identified / Removed

Tag

Len

Value(s) / Description

C0

01

03

Message Type Data Object (Tag C0) = 0x03 Notification

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

40

Command ID Data Object (Tag C2) = 0x40 Card Inserted/Identified/Removed

C4

02

Data Field Data Object (Tag C4 or E0) = Byte 0: Card Present Indication (CPI)

· 0x00 = Card was present and has been removed

· 0x01 = Card was not present and is now present

Byte 1: Card Type Present Indication (IPI)

· 0x00 = Card is not a chip card (ICC card)

· 0x01 = Card is a chip card (ICC card)

Command 0x01::0x50 - Subscribe to Notifications

The host uses this command to specify which notifications the device should send to it (for example, Notification 0x01::0xFF - Device Reset). By default, the device does not send any notifications to the host.

Table - Message Structure for Command 0x01::0x50 - Subscribe to Notifications

Tag

Len

Value(s) / Description

C0

01

01

Message Type Data Object (Tag C0) = 0x01 Command

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

50

Command ID Data Object (Tag C2) = 0x50 Subscribe to Notifications

C4

Calculated

Data Field Data Object (Tag C4 or E0) = Byte 0 Subscribe or Unsubscribe

0x01 = Subscribe 0x02 = Unsubscribe

Byte 1 Notifications to Subscribe To

0x00 = Subscribe/unsubscribe to all notifications 0x01 = Subscribe/unsubscribe to specific notifications

If Notifications to Subscribe To = 0x01:

Bytes 2..n contain a list of two-byte notification IDs which specify the Application Group and Notification Number of each Notification the device should send to the host. For example, to subscribe to Notification 0x01::0xFF - Device Reset, the host would include 0x010F as two bytes in the list.

Table - Response to Command 0x01::0x50 - Subscribe to Notifications

Tag

Len

Value(s) / Description

C0

01

02

Message Type Data Object (Tag C0) = 0x02 Response

C1

01

01

Application ID Data Object (Tag C1) = 0x01 General Messages

C2

01

50

Command ID Data Object (Tag C2) = 0x50 Subscribe to Notifications

C3

01

Result Code Data Object (Tag C3)

Last updated