# XPI Static IP Configuration Ref Guide This feature is required for the device to be able set/get the network configuration details at runtime by sending a packet to XPI. | Requirement | Description | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | | Updating static IP on device from POS | POS should be able to set up the static IP configuration for any interface at runtime by sending a command. | | Fetching the IP/Network config details from the device | POS should be able to query the active IP configuration for any interface at runtime by sending a command. | ## Proposed Solution(s) Introduce a new command to configure or fetch the network configuration on the device. ### Request Command details can be as below: **XNETCONF** {% code title="Packet format" %} ``` ``` {% endcode %} | Field | Length | Mandatory/Optional | Description | | -------- | ------ | ------------------ | ----------------------------------------------------------------------------------------- | | | 1H | Mandatory | Start Sentinel | | XNETCONF | 8A | Mandatory | Packet ID | | | 1H | Mandatory | Field separator | | | 2N | Mandatory | Operation to be performed. See below for details | | | 1H | Mandatory | Field separator | | | 4H | Mandatory | Desired network interfaces for which the operation is intended for. See below for details | | | 1H | Optional | Field separator. If Action code = 1, then it's mandatory | | | ?AN | Optional | Interface configuration details. If Action code = 1, then it's mandatory | | | 1H | Mandatory | End Sentinel | | | 1H | Mandatory | Longitudinal Redundancy check | **- (2N)** * 0 - Fetch the interface details for the interfaces set in field. * 1 - Set the configuration for the interfaces set in field. **- (4H)** | Bitmap | Interface | | ------ | --------- | | 1 | Ethernet | | 2 | WiFi | | 4 | USB\_LAN | | 8 | BT\_LAN | **\ - (?AN)** | Field | Value Type | Application Values | Mandatory/Optional | Applicability | | --------- | ----------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------- | | interface | string | "0" – Ethernet "1" – WiFi "4" - IP Over USB (USB\_LAN) "8" - IP Over Bluetooth (BT\_LAN) | Mandatory | Request (Action code = 1) | | dhcp | string | "0", "1" | Optional. Default = "1" (If not present or invalid value). Ignored when action code = 4 | Request (Action code = 1) | | ip\_addr | string/IP address | | Mandatory if dhcp=0 & action code = 1, ignored if dhcp=1 | Request (Action code = 1) | | gateway | string/IP address | | Mandatory if dhcp=0 & action code = 1, ignored if dhcp=1 | Request (Action code = 1) | | dns\_1 | string/IP address | | Mandatory if dhcp=0 & action code = 1, ignored if dhcp=1 | Request (Action code = 1) | | dns\_2 | string/IP address | | Optional | Request (Action code = 1) | | WIFI\_APs | JSON Array | | Mandatory for WiFi interface | Request (Action code = 1) | Fields in WIFI\_APs elements: | Field | Description | Value Type | Mandatory/Optional | | ---------- | ----------------------------------------------------------- | ---------- | --------------------------------------------------------- | | ssid | WiFi SSID to connect to. | string | Mandatory | | psk | Password for the WiFi SSID. | string | Mandatory | | visibility | whether the WiFi SSID is hidden or visible to the terminal. | string | Optional. Default = "1" (If not present or invalid value) |
NOTE * All fields & values are case sensitive. * For action code 0 the Interface configuration field would not be required and if present in the request will be ignored.
#### Sample Interface Configuration Details (JSON array format) Ethernet ```json [ { "interface": "1", "dhcp": "0", "ip_addr": "10.120.10.1", "netmask": "255.255.255.0", "gateway": "10.120.10.0", "dns_1": "8.8.8.8", "dns_2": "8.8.4.4" } ] ``` WiFi ```json [ { "interface": "2", "dhcp": "1", "WIFI_APs": [ { "ssid": "ssid1", "psk": "Password1", "visibility": "1" } ] } ] ``` Static WiFi ```json [ { "interface": "2", "dhcp": "0", "ip_addr": "10.120.10.1", "netmask": "255.255.255.0", "gateway": "10.120.10.0", "dns_1": "8.8.8.8", "dns_2": "8.8.4.4", "WIFI_APs": [ { "ssid": "ssid1", "psk": "Password1", "visibility": "1" } ] } ] ``` IP Over USB - USB\_LAN ```json [ { "interface": "4", "dhcp": "0", "ip_addr": "192.168.137.3", "netmask": "255.255.255.0", "gateway": "192.168.137.1", "dns_1": "8.8.8.8", "dns_2": "8.8.4.4" } ] ``` Combined Ethernet and WiFi Network configuration (example) ```json [ { "interface": "4", "dhcp": "0", "ip_addr": "10.120.10.1", "netmask": "255.255.255.0", "gateway": "10.120.10.0", "dns_1": "8.8.8.8", "dns_2": "8.8.4.4" }, { "interface": "2", "dhcp": "1", "WIFI_APs": [ { "ssid": "ssid1", "psk": "Password1", "visibility": "1" } ] } ] ``` #### Sample Commands * Fetch Ethernet network details: * `XNETCONF000001` * Set Ethernet network to a static configuration: * `XNETCONF010001[{"interface":"1","dhcp":"0","ip_addr":"10.120.10.1","netmask":"255.255.255.0","gateway":"10.120.10.0","dns_1":"8.8.8.8","dns_2":"8.8.4.4"}]` * Invalid Command: * `XNETCONF010001[{"interface":"14","dhcp":"0","ip_addr":"10.120.10.1","netmask":"255.255.255.0","gateway":"10.120.10.0","dns_1":"8.8.8.8","dns_2":"8.8.4.4"}]` *** ### Response **XNETCONF** {% code title="Response packet format" %} ``` ``` {% endcode %} | Field | Length | Presence | Description | | -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 1H | Always | Start Sentinel | | XNETCONF | 8A | Always | Packet ID | | | 1H | Always | Field separator | | | 2N | Always | Result code for the command. See below for details | | | 1H | Always | Field separator | | | ?AN | Always | In case of a valid command: For action code = 0 this will return the network configuration details for the requested interfaces. For action code = 1 this will return the new applied network configuration details. In case of an invalid command this will return details on why the command was considered invalid. | | | 1H | Always | End Sentinel | | | 1H | Always | Longitudinal Redundancy check | **- (2N)** * This can be a Bitmap according to the requested Interface Bitmap in the request. * 00 - Success. If the action code=1 in the request, the response string will contain the interface config details in the response. In case of success, the active network details would be returned in the response for action code 0/1 along with the error details for any interface. For action code = 0, it should not return an error; if any network is not up, rather it should return "Interface is not up". * 01 - Partial Success (some of the operation failed). Check the Response string JSON for more details. The active network details would be returned along with error details for any interface. * 02 - Failure - All operations failed. Check the Response string JSON for details. * 03 - Invalid command. Possible scenarios include: * Invalid action code * Invalid Interface Bitmap * Invalid Interface configuration received (e.g. static IP but a required field such as gateway/dns/ip addr is missing) * Mismatch between the Interface bitmap and Interface configuration JSON string (e.g. Interface bitmap includes ethernet, but no ethernet configuration received for action code 1) * Incomplete interface configuration JSON string * Action code = 1 (partial update), but existing network type is DHCP * Action code = 1, WiFi is set in the interface bitmap, but the WiFi configuration does not contain any SSID configuration. **- (?AN)** This response string will be JSON array formatted data. Example: ```json [ { "result": "Success", "interface": "1", "error_string": "None", "network_config": { "dhcp": "0", "ip_addr": "10.120.10.1", "netmask": "255.255.255.0", "gateway": "10.120.10.0", "dns_1": "8.8.8.8", "dns_2": "8.8.4.4" } }, { "result": "Success", "interface": "2", "error_string": "None", "network_config": { "dhcp": "0", "ip_addr": "10.120.10.1", "netmask": "255.255.255.0", "gateway": "10.120.10.0", "dns_1": "8.8.8.8", "dns_2": "8.8.4.4", "ssid": "ssid1" } }, { "result": "Failure", "interface": "4", "error_string": "Interface not up" } ] ``` **Response String JSON Fields** | Field | Value Type | Application Values | Applicability | | --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | result | string | "Success", "Failure" | Response (Action code = 0/1) | | error\_string | string |

"None" - No Error. Anything else (available when result = "Failure") may include:

  • Invalid command - Reason why command was treated as invalid.
  • The error string returned by ADK-COM
| Response (Action code = 0/1) | | interface | string | "0" - Ethernet "1" - WiFi "4" - IP Over USB (USB\_LAN) "8" - IP Over Bluetooth (BT\_LAN) | Response (Action code = 0/1), for valid command. | | network\_config | JSON object | | Response (Action code = 0/1), for valid command & if the network operation for the desired interface was performed successfully. | network\_config element fields (available if the respective interface is up and result = "Success"): | Field | Value Type | Application Values | Applicability | | -------- | ----------------- | ------------------ | ----------------------------------------------------- | | dhcp | string | "0", "1" | Response (Action code = 0/1) | | ip\_addr | string/IP address | | Response (Action code = 0/1) | | gateway | string/IP address | | Response (Action code = 0/1) | | dns\_1 | string/IP address | | Response (Action code = 0/1) | | dns\_2 | string/IP address | | Response (Action code = 0/1) | | ssid | string | | Response (Action code = 0/1). Only for WiFi interface | #### Sample Responses * Fetch Ethernet network details: ``` XNETCONF00[{"result":"Success","interface":"1","error_string":"None","network_config":{"dhcp":"0","ip_addr":"10.120.10.1","netmask":"255.255.255.0","gateway":"10.120.10.0","dns_1":"8.8.8.8","dns_2":"8.8.4.4"}}] ``` * Set Ethernet network to a static configuration: ``` XNETCONF00[{"result":"Success","interface":"1","error_string":"None","network_config":{"dhcp":"0","ip_addr":"10.120.10.1","netmask":"255.255.255.0","gateway":"10.120.10.0","dns_1":"8.8.8.8","dns_2":"8.8.4.4"}}] ``` * Invalid command response: ``` XNETCONF03[{"result":"Failure","error_string":"INVALID COMMAND - Invalid interface bitmap"}] ```
NOTE * For action code 1, if any incoming interface is not already up, application will try to start/bring up the interface and then configure the network for the same. * In case of a static network configuration, action code 1 can be used to partially update the network configuration as well. * For WiFi, only PSK key management mode is supported; EAP key management mode is not supported. * For all the networks, once configured the network will be brought up automatically upon every device boot up.
*** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.verifone.com/xpi/tbd-documentation/engage-miscellaneous/xpi-static-ip-configuration-ref-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.