Display Control (Screen Display) - Nayax Developer Portal

Display Control is a Preselection feature that allows a transaction process to begin by selecting a product on the Nayax device, with the consumer selecting the desired product by touching the relevant screen on the device. The configuration of said screens can be done in 2 ways: The first, more common one, is done via the “Display Control” command to the device, which can be sent from the peripheral at any point of the device being in idle- meaning once “onReady()” has been triggered:

"vmc_vend_event_on_ready" event 
in vmc_vend_event_handler_cb

This event means that: • The VPOST/VPOSM device is fully initialized • Communication is established and stable • The system is ready to accept Display Control commands Implementation Example: For the C SDK, you can see this pattern in the provided example code in mymain_always_idle.c:

static __bool vmc_vend_event_handler_cb(int event_id, void *data)
{
    switch (event_id)
    {
        case vmc_vend_event_on_ready:
            // This is the correct place to send display control
            handler_display_control(&display);
            break;
        // ... other cases
    }
    return result;
}

Important Notes - C SDKRequired Configuration ChangePlease also make this important configuration update in your project: File: makefile.include Change: Set MARSHALL_MSG_ARRAY_SIZE to 4 MARSHALL_MSG_ARRAY_SIZE = 4This ensures sufficient message buffer allocation for display control operations.• Do not modify any files in vpos (such as vmc_vend.c, vmc_link.c)• Using vmc_vend_event_on_ready ensures proper timing without arbitrary delays

The second is via sending a command via Nayax Core (Nayax’s backoffice)- more on that bellow.

Note:

The device’s limitation is up to 12 objects per Layout.
Use %c in the beginning of the label value to show a clock icon.

Once either configuration has been sent, it will remain on the device (no need to resend it after every transaction; only after the pairing process).

Updating the Screens

As can be seen in the PowerPoint above, once the Display Control command has been sent, the device would respond with a Display Status command, letting it know whether or not the device received said command and it’s validity.

Starting a Transaction

Once a consumer has selected a product (screen) on the device, the device would respond with information the peripheral regarding which screen was selected, to which it should respond with a “Vend Request” with the relevant product code and price in order for the transaction process to begin.

Possible Layouts- VPOST only (except for layouts 7,8 which are also relevant for Media)

Layouts Relevant for VPOSM Only:

Layout Examples

Layout ID 1

                // allocate layout
                marshall_t.msg_display_control_t.layout_t ui_context = m_vmc.general.display_control_create_layout(1);

                // add label
                m_vmc.general.display_control_layout_add_label(ui_context, 0, 0, "Layout 2x3");

                m_vmc.general.display_control_layout_add_label(ui_context, 1, 0, "Text 1");
								m_vmc.general.display_control_layout_add_label(ui_context, 1, 1, "Text 2");
								m_vmc.general.display_control_layout_add_label(ui_context, 1, 2, "%cText 3");

                m_vmc.general.display_control_layout_add_label(ui_context, 2, 0, "Text 1");
                m_vmc.general.display_control_layout_add_label(ui_context, 2, 1, "Text 2");
								m_vmc.general.display_control_layout_add_label(ui_context, 2, 2, "%cText 3");

                // apply layout on screen
                m_vmc.general.display_control_apply_layout(ui_context);
       

Layout ID 2

                // allocate layout
                marshall_t.msg_display_control_t.layout_t ui_context = m_vmc.general.display_control_create_layout(2);

                // add label
                m_vmc.general.display_control_layout_add_label(ui_context, 0, 0, "Layout 2x2");

								m_vmc.general.display_control_layout_add_label(ui_context, 1, 0, "Text 2");
								m_vmc.general.display_control_layout_add_label(ui_context, 1, 1, "%cText 3");

                m_vmc.general.display_control_layout_add_label(ui_context, 2, 0, "Text 2");
								m_vmc.general.display_control_layout_add_label(ui_context, 2, 1, "%cText 3");

                // apply layout on screen
                m_vmc.general.display_control_apply_layout(ui_context);
       

Layout ID 3

                // allocate layout
                marshall_t.msg_display_control_t.layout_t ui_context = m_vmc.general.display_control_create_layout(3);

                // add label
                m_vmc.general.display_control_layout_add_label(ui_context, 0, 0, "Layout 4x1");

								m_vmc.general.display_control_layout_add_label(ui_context, 1, 0, "Text 1");

                m_vmc.general.display_control_layout_add_label(ui_context, 2, 0, "Text 2");

								m_vmc.general.display_control_layout_add_label(ui_context, 3, 0, "Text 3");

								m_vmc.general.display_control_layout_add_label(ui_context, 4, 0, "Text 4");

                // apply layout on screen
                m_vmc.general.display_control_apply_layout(ui_context);

Layout ID 4

                // allocate layout
                marshall_t.msg_display_control_t.layout_t ui_context = m_vmc.general.display_control_create_layout(4);

                // add label
                m_vmc.general.display_control_layout_add_label(ui_context, 0, 0, "Layout 4x2");

								m_vmc.general.display_control_layout_add_label(ui_context, 1, 0, "Text");
								m_vmc.general.display_control_layout_add_label(ui_context, 1, 1, "%cText");

                m_vmc.general.display_control_layout_add_label(ui_context, 2, 0, "Text");
                m_vmc.general.display_control_layout_add_label(ui_context, 2, 1, "%cText");

								m_vmc.general.display_control_layout_add_label(ui_context, 3, 0, "Text");
								m_vmc.general.display_control_layout_add_label(ui_context, 3, 1, "%cText");

								m_vmc.general.display_control_layout_add_label(ui_context, 4, 0, "Text");
								m_vmc.general.display_control_layout_add_label(ui_context, 4, 1, "%cText");

                // apply layout on screen
                m_vmc.general.display_control_apply_layout(ui_context);
       

Layout ID 5

                // allocate layout
                marshall_t.msg_display_control_t.layout_t ui_context = m_vmc.general.display_control_create_layout(5);

                // add label
                m_vmc.general.display_control_layout_add_label(ui_context, 0, 0, "Layout 6x1");

								m_vmc.general.display_control_layout_add_label(ui_context, 1, 0, "13");

                m_vmc.general.display_control_layout_add_label(ui_context, 2, 0, "14");

								m_vmc.general.display_control_layout_add_label(ui_context, 3, 0, "15");

								m_vmc.general.display_control_layout_add_label(ui_context, 4, 0, "16");

								m_vmc.general.display_control_layout_add_label(ui_context, 5, 0, "17");

								m_vmc.general.display_control_layout_add_label(ui_context, 6, 0, "18");

                // apply layout on screen
                m_vmc.general.display_control_apply_layout(ui_context);

Layout ID 6

                // allocate layout
                marshall_t.msg_display_control_t.layout_t ui_context = m_vmc.general.display_control_create_layout(6);

                // add label
                m_vmc.general.display_control_layout_add_label(ui_context, 0, 0, "Layout 6x2");

								m_vmc.general.display_control_layout_add_label(ui_context, 1, 0, "13");
								m_vmc.general.display_control_layout_add_label(ui_context, 1, 1, "5");

                m_vmc.general.display_control_layout_add_label(ui_context, 2, 0, "14");
								m_vmc.general.display_control_layout_add_label(ui_context, 2, 1, "5");

								m_vmc.general.display_control_layout_add_label(ui_context, 3, 0, "15");
								m_vmc.general.display_control_layout_add_label(ui_context, 3, 1, "5");

								m_vmc.general.display_control_layout_add_label(ui_context, 4, 0, "16");
								m_vmc.general.display_control_layout_add_label(ui_context, 4, 1, "5");

								m_vmc.general.display_control_layout_add_label(ui_context, 5, 0, "17");
								m_vmc.general.display_control_layout_add_label(ui_context, 5, 1, "5");

								m_vmc.general.display_control_layout_add_label(ui_context, 6, 0, "18");
								m_vmc.general.display_control_layout_add_label(ui_context, 6, 1, "5");

                // apply layout on screen
                m_vmc.general.display_control_apply_layout(ui_context);
       

Layout ID 7

**Note: **You can have up to 6 values: values 4-6 would appear once you scroll down.

                // allocate layout
                marshall_t.msg_display_control_t.layout_t ui_context = m_vmc.general.display_control_create_layout(7);

                // add label
                m_vmc.general.display_control_layout_add_label(ui_context, 0, 0, "Layout H Scroll 1");

								m_vmc.general.display_control_layout_add_label(ui_context, 1, 0, "Text value 1");

                m_vmc.general.display_control_layout_add_label(ui_context, 2, 0, "Text value 2");

								m_vmc.general.display_control_layout_add_label(ui_context, 3, 0, "Text value 3");

								m_vmc.general.display_control_layout_add_label(ui_context, 4, 0, "Text value 4");

								m_vmc.general.display_control_layout_add_label(ui_context, 5, 0, "Text value 5");

								m_vmc.general.display_control_layout_add_label(ui_context, 6, 0, "Text value 6");

                // apply layout on screen
                m_vmc.general.display_control_apply_layout(ui_context);

Layout ID 8

**Note: **You can have up to 6 values: values 4-6 would appear once you scroll down.

                // allocate layout
                marshall_t.msg_display_control_t.layout_t ui_context = m_vmc.general.display_control_create_layout(8);

                // add label
                m_vmc.general.display_control_layout_add_label(ui_context, 0, 0, "Layout H Scroll 2");

								m_vmc.general.display_control_layout_add_label(ui_context, 1, 0, "Text value 1");
								m_vmc.general.display_control_layout_add_label(ui_context, 1, 1, "10");

                m_vmc.general.display_control_layout_add_label(ui_context, 2, 0, "Text value 2");
								m_vmc.general.display_control_layout_add_label(ui_context, 2, 1, "20");

								m_vmc.general.display_control_layout_add_label(ui_context, 3, 0, "Text value 3");
								m_vmc.general.display_control_layout_add_label(ui_context, 3, 1, "30");

								m_vmc.general.display_control_layout_add_label(ui_context, 4, 0, "Text value 4");
								m_vmc.general.display_control_layout_add_label(ui_context, 4, 1, "40");

								m_vmc.general.display_control_layout_add_label(ui_context, 5, 0, "Text value 5");
								m_vmc.general.display_control_layout_add_label(ui_context, 5, 1, "50");

								m_vmc.general.display_control_layout_add_label(ui_context, 6, 0, "Text value 6");
								m_vmc.general.display_control_layout_add_label(ui_context, 6, 1, "60");


                // apply layout on screen
                m_vmc.general.display_control_apply_layout(ui_context);
       

Layout ID 9- VPOSM only!

m_vmc.general.display_control_layout_add_label(ui_context, 0, 0, "Do You Want A Receipt?");

m_vmc.general.display_control_layout_add_label(ui_context, 1, 0, "Yes");
m_vmc.general.display_control_layout_add_label(ui_context, 1, 1, "@shapes/positive");

m_vmc.general.display_control_layout_add_label(ui_context, 2, 0, "No");
m_vmc.general.display_control_layout_add_label(ui_context, 2, 1, "@shapes/square");

One or two big buttons will appear in the middle. The first is in yellow and text in black, and the other (if it exists) is in black with text in white.

Layout ID 10- VPOSM Only

m_vmc.general.display_control_layout_add_label(ui_context, 0, 0, "Ready To refuel");

// add label
m_vmc.general.display_control_layout_add_media(ui_context, 1, "@assets/x_red.png");

Including title (optional, can be Null), and the element to be presented (Image/Animation).

Layout ID 11- VPOSM Only

m_vmc.general.display_control_layout_add_label(ui_context, 0, 0, "Loyalty");
m_vmc.general.display_control_layout_add_input(ui_context, 1, 1, 15, "Phone Number");
//for the optional button:
m_vmc.general.display_control_layout_add_label(ui_context, 2, 0, "Optional Button");

Including: Title, Subtitle, and Input Field

Nayax Core configurations

Important:This feature is supported only in “Always Idle” mode. This means that you need to have “Always Idle” configuration set up both on the device level (via Nayax Core) as well as have it be set to “true” on the peripheral level (via the SDK)You can see the flag’s location in the SDK Flagspage, under “Configurations flags”.

Attribute Group	Attribute Name	Attribute Value
MDB	Cashless MDB address	Marshall VMC
	MDB flags	02 Preselection Enabled
	MDB Level 3 Optional Features	Enable “Always Idle” state
Card Readers	Card Reader MDB Level	3
	Transaction start method	Product
	Transaction Start Ignore List	Ignore None
	VPOS Read Source Enabled	All Read Sources Enabled (Default)
	VPOS Button Function	01 External cancel
Payment	Choose Product Timeout	> 0
	Default Credit	> 0 (highest product’s amount)
	EMV Price Table	C%100
	Payment Flags	Allow Pre-Selection on Pre-Paid cards
VMC	Session Time Out (minutes)	> 0

Updating the Screens via Nayax Core

A Nayax Core attribute has been introduced that allows operators to dynamically update text, prices, and configurations on selection screens- the screens that appear when the device is in idle mode, waiting for a consumer to select a product by selecting (touching) one of said screens. This attribute enables sending structured data from Nayax Core to the peripheral. This information is then processed and displayed on the Marshall selection screen. The attribute definition is as follows:

Attribute	Value
ID	7700
Name	Marshall Screens Info
Group	VMC
Maximum Length	400 characters

This sends a JSON-formatted string containing details about selection screens, including layout configurations, text labels, prices, and timing.

JSON Logic Recommendation

The JSON string should include necessary instructions for each selection screen. The format is flexible, allowing operators to specify only the required parameters. See the structure in the code block below:

{
  "Screen Name 1": {
    "layout_id": <ID>,
    "content": {
      "layout_title": "<title>",
      "text_1": "<text>",
      "text_2": "<text>",
      "text_3": "<text>",
      "text_4": "<text>"
    },
    "prices": {
      "price_1": "<price>",
      "price_2": "<price>"
    },
    "timing": {
      "time_1": "<time>",
      "time_2": "<time>"
    },
    "buttons": "<comma-separated list of button IDs>"
  },
  "Screen Name 2": {
    "layout_id": <ID>,
    "content": { ... },
    "prices": { ... }
  }
}

Validate the JSONThe JSON validity and defined prices are solely the operator’s responsibility. It is highly recommended to validate the JSON using a JSON validator before sending it to a remote machine since incorrectly formatted JSON may cause display errors or unexpected behavior.

Example

See the JSON below. It is sending the instructions to update the display of an Air Vac machine.

{
  "Select product from 2 options": {
    "layout_id": 2,
    "content": {
      "layout_title": "Select Air/Vac",
      "text_1": "Air",
      "text_2": "$2",
      "text_3": "%c 5 min",
      "text_4": "Vac",
      "text_5": "$3",
      "text_6": "%c 10 min"
    },
    "prices": {
      "price_1": "2",
      "price_2": "3"
    },
    "buttons": "104"
  }
}

The packet built from this JSON is the following:

Packet = 0x01 0x02 0x0100 
0x02 0x0C 0x00 0x00 “Select Air/Vac”
0x02 0x08 0x01 0x00 “Air” 
0x02 0x08 0x01 0x01 “$2”
0x02 0x08 0x01 0x02 “%c 5 min”
0x02 0x08 0x02 0x00 “Vac”
0x02 0x08 0x02 0x01 “$3” 
0x02 0x08 0x02 0x02 “%c 10 min”
0x03 0x01 0x68

Packet CreationPackets are created automatically by the SDK or Nayax Core.

The image below would be the display result.

Guides

​Display Control Related Commands

​Updating the Screens

​Starting a Transaction

​Possible Layouts- VPOST only (except for layouts 7,8 which are also relevant for Media)

​Layouts Relevant for VPOSM Only:

​Layout Examples

​Layout ID 1

​Layout ID 2

​Layout ID 3

​Layout ID 4

​Layout ID 5

​Layout ID 6

​Layout ID 7

​Layout ID 8

​Layout ID 9- VPOSM only!

​Layout ID 10- VPOSM Only

​Layout ID 11- VPOSM Only

​Nayax Core configurations

​Updating the Screens via Nayax Core

​JSON Logic Recommendation

​Example

Display Control Related Commands

Updating the Screens

Starting a Transaction

Possible Layouts- VPOST only (except for layouts 7,8 which are also relevant for Media)

Layouts Relevant for VPOSM Only:

Layout Examples

Layout ID 1

Layout ID 2

Layout ID 3

Layout ID 4

Layout ID 5

Layout ID 6

Layout ID 7

Layout ID 8

Layout ID 9- VPOSM only!

Layout ID 10- VPOSM Only

Layout ID 11- VPOSM Only

Nayax Core configurations

Updating the Screens via Nayax Core

JSON Logic Recommendation

Example