> For the complete documentation index, see [llms.txt](https://sandbox-docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sandbox-docs.verifone.com/adk-5.0-programmers-guide/readme/developing_applications/pg_all_packages.md).

# ADK packages and available download files

This document provides information about the ADK package (archives) structure, as well as download files to load software into terminal devices and update procedures.

## Definitions <a href="#sec_definitions" id="sec_definitions"></a>

**ADK Packages (archive):** An ADK package, which is usually a zip archive following an ADK directory structure, combines SDK like content and tools, to build and package applications, documentation, sample code, as well as download files to load executables and other files into the terminal.

**Download file:** A download file is used to load content into the terminal. It is "ready-for-use" signed in case of operating system and middleware components for V/OS1 and V/OS2 based devices. It is un-signed, in case of user components. The use of bundled download files is recommended, usage of individual component download files is not recommended. V/OS3 provides additional files for appdev devices, identified by the "-dev" qualifier in the name.

## Platforms <a href="#sec_platforms" id="sec_platforms"></a>

The following platform names are used in ADK packages:

| Platform           | Description                              |
| ------------------ | ---------------------------------------- |
| vos                | V/OS Platform for Trident based HW       |
| vos2               | V/OS Platform for Raptor based HW        |
| vos3               | V/OS Platform for Neo and Vegas based HW |
| win32, win64 (x86) | Windows platforms                        |

{% hint style="info" %}
Not all packages are supported on all platforms.
{% endhint %}

### Component Names <a href="#subsec_components" id="subsec_components"></a>

Please see ADK component names and links to detailed information for use at [ADK Components](/adk-5.0-programmers-guide/readme/system_overview/pg_all_components.md#sec_components).

### Version Strings <a href="#subsec_version" id="subsec_version"></a>

All \<version> strings follow the format: \<major>.\<minor>.\<patch>-\<build suffix> The "build suffix" is generated by the Build Server.

## ADK Package Format <a href="#sec_comp_pkg" id="sec_comp_pkg"></a>

Every ADK package is a ZIP file, which follows the same folder structure inside its archive. Not all packages include every directory, but the ones included follow this structure: **\<component>-full-\<version>**.zip with following folder structure.

```cpp
<root>
   |-<component>-versioninfo.txt
   |- doc
   |-<platform>
   |- include
   |-<component>
   |-<header>.h
   |- lib
   |-lib[<prefix>]<component>[<suffix>].a (static library)
   |-lib[<prefix>]<component>[<suffix>].so (shared library)
   |- load
   |-<component>
   |-dl.[<prefix>]<component>[<suffix>][-remove]-<version>[-prod].[tar, tgz] (V/OS)
   |- tools
   |-<component>
   |-<tool-executable>-<version>.[exe, zip, rpm, tar, ...]
```

| Folder  | Content                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| doc     | Component documentation organized in a separate subfolder per component. This could include sample code or configuration or even loadable packages. |
| lib     | Component libraries in a flat folder structure including static and shared library files                                                            |
| include | Component public header files organized in separate subfolders per component. There might be more than one header file per component.               |
| load    | Download packages are organized in subfolder. \<prefix> and \<suffix> are optional and might indicate variants.                                     |
| bin     | Component executables and shell scripts in separate subfolders per component                                                                        |
| tools   | Component tools organized in separate subfolder per component. Typically these tools run on host development platforms like win32.                  |

### Software Development Kits <a href="#subsec_sdkpacks" id="subsec_sdkpacks"></a>

adk-sdk-\<platform>-version: SDK package per platform, including header files and libraries to build applications. These can be used stand alone or as part of VDE.

### Documentation Packages <a href="#subsec_docpacks" id="subsec_docpacks"></a>

* adk-overview-programmers-guide-\<version>: Main documentation package for all platforms
* adk-doc-\<version>: Additional files and tools, which is referenced by the programers guide, as well as the detailed version information of the release.

The ADK doc package contain the adk-versioninfo.txt file, which lists the versions of integrated ADK components.

```cpp
<component> <version><build_suffix> <revision> <timestamp>
<component> <version><build_suffix> <revision> <timestamp>
...
<component> <version><build_suffix> <revision> <timestamp>
```

Revisions are unique identifiers like GIT hashes.

### ADK Version Information <a href="#subsec_comp_pkg_adkversioninfo" id="subsec_comp_pkg_adkversioninfo"></a>

#### V/OS, V/OS2 <a href="#subsubsec_comp_pkg_adkversioninfo_legacy_vos" id="subsubsec_comp_pkg_adkversioninfo_legacy_vos"></a>

Starting with ADK 4.9, ADK solution download files include a pseudo component SLP (Software Licensing and Protection). The SLP component does not provide any active functionality. The only intention of this component is to provide release version information of the ADK installed on a payment terminal device.

### SLP Tainted Status (V/OS2 only) <a href="#subsec_comp_pkg_slptainted" id="subsec_comp_pkg_slptainted"></a>

During the boot process, the system compares the actual installed bundle version with the expected secure version defined by the ''policy'' in the SLP file.

On V/OS2 devices, the SLP status TAINTED is returned if one of the following conditions is true:

* SLP file is missing
* Software component versions mismatch

If the SLP status is TAINTED, then the device displays the NAG screen "SLP TAINTED".

{% hint style="info" %}
It is not possible to delete the TAINTED status from the device. Only installation of an ADK solutions package will reset the SLP status.
{% endhint %}

The SLP status is also displayed in the:

* boot screen: `SLP` `TAINTED` or `SLP` `OK`,
* Sysmode / Basic Information, in the field "SLP Status".

The SLP status can also be retrieved in a user applications by the ADK-SYS read-only property `SYS_PROP_SLP_TAINTED_STATUS` (see [sysGetPropertyInt()](/adk-5.0-programmers-guide/readme/modules/group__led/namespacevfisysinfo.md#ab94a5b33000760afbee10e7fefd16355) for details).

#### V/OS3 <a href="#subsubsec_comp_pkg_adkversioninfo_vos3" id="subsubsec_comp_pkg_adkversioninfo_vos3"></a>

{% hint style="info" %}
V/OS3 does not make use of a 'TAINTED' state but implements proper dependency tracking within bundle manifests. If there's a mismatch between pre-defined versions and what's finally in the dl file, the installation will cancel. See V/OS3 installer section for details. The actual version of each component is determined during the build and cannot be changed afterwards.
{% endhint %}

## Download Files <a href="#sec_solution_dl_files" id="sec_solution_dl_files"></a>

### V/OS Load Packages <a href="#subsec_comp_pkg_vosloadpkg" id="subsec_comp_pkg_vosloadpkg"></a>

V/OS download files are named following this scheme:

```cpp
<component>/dl.[<prefix>]<component>[<suffix>][-remove]-<version>[-prod|dev].[tar|tgz]
```

* Download files on V/OS or V/OS2 are compressed archives to load content into a terminal device.
* V/OS3 download files are not compressed, however its content is. The content is secured in a different way than on V/OS and V/OS2, please check the installer chapter for details.
* Removal packages add "-remove" after the suffix and before the version
* Productive packages: Add "-prod" after the version, if production signed
* Appdev packages (V/OS3 only): Has '-dev' after the version number
* User packages must be signed online on the Verifone File Signing (VSP) portal. Physical customer specific signing cards are not available for V/OS3. See [Online Signing Portal](/adk-5.0-programmers-guide/readme/developing_applications/pg_package_signing.md#subsec_package_signing_fsp) for details.
* Applications may provide download packages for shared libraries. In a multi-application environment, multiple processes may use the shared libraries for importing a service (e.g. libvfigui.so for GUI service) instead of static library to reduce code sizes. ADK shared libraries for V/OS have set group to "share", in order to grant access to other users (usr1 - usr16).

### ADK Load Package Archive <a href="#subsec_loadpacks" id="subsec_loadpacks"></a>

adk-load-\<platform>-version: Archives containing ADK solution download files for production and appdev development devices for each platform, as well as optional download files. VOS3 comes with one additional "dev" archive for application development and devkit devices.

### ADK Solution Download Files <a href="#subsec_downloadfiles" id="subsec_downloadfiles"></a>

The ADK load package provides integrated solutions download files, which include a full set of components, for both the operating system and middleware. Installing a solutions file usually removes all components from older solution bundles, but doesn't affect user application or configuration bundles in R/W memory.

Multiple solution packages may exist per platform to support different use cases (e.g. SDI or headless use on Engage/Android devices). Whenever possible, the use of solution packages is highly recommended.

{% hint style="info" %}
The deployer of the terminal must ensure that only software that has all necessary certifications is deployed to the field. Existence of a solution package is in no way intending that software can be rolled out in the field without this review.
{% endhint %}

Solution packages are available in load/solutions folder inside the ADK load package [ADK Load Package Archive](#subsec_loadpacks) in the respective platform folders.

### Upgrader Download Files <a href="#subsec_update_files" id="subsec_update_files"></a>

The purpose of upgrader packages is to provide customers an easy way to upgrade devices in the field to a specific target version. Those files have a reduced size compared to regular download files and it will not modify configuration or certificate files.

Types of upgrader:

* **Diff-Patch**: A patch is a binary differential between two versions. It is created based on a specific source and a specific destination. A patch install package can't be installed on any other version than specified.

Components affected: The default upgrader will upgrade the whole system, the OS and the middleware components in one file. In some cases, separate upgrader for the middleware or the OS are provided in addition. See release notes document for details.

**Naming** **convention:** Upgrade packages have the following naming convention:

dl.adk-\<ADK-target-version>-\<vos2|vos>-\<device-type>-\<sparse|diff>\_\<ADK-start-version>-prod.tgz

### System Installation Download Files <a href="#subsec_installdlfiles" id="subsec_installdlfiles"></a>

**System Install (V/OS, V/OS2, V/OS3):** These type of files are used for a clean system installation, e.g. in a deployment centre or during development. In contrast to updater packages, those ones remove all bundles and packages from a device except user signed content, prior to installation.

* **vos3-\<version>-(neo|vegas)-prod**: Combined download file for V/OS3 devices. Those packages have system signed OS and ADK middleware components and can be installed on all Neo or Vegas devices respectively. These download files do **not** include updates for the secure processor or non-hlos firmware binaries. These must be loaded separately. Component packages and versions are tied down and cannot be exchanged with other versions, with the notable exception of the VHQ agent. Please contact VFI support for a hot fix build, if needed.
* **vos3-\<version>-\<device>-prod**: These files contain the same binaries as the file above, but have to be used to update V/OS3 versions 1.1.x, 1.0.x and older.
* **secproc-fw-\<version>-prod**: These files allow the update of the secure processor. The secure processor firmware undergoes independent PCI approvals. Please check the certification state for these firmware files carefully before use. A default file is provided, but newer versions can be loaded on top of a given release.
* **\<neo|neo2>-non-hlos\_\<device>-\<version>-prod**: These files update specific parts of the firmware, which are large and don't change often. Please apply updates on top of the regular download files.
* **vos2-engage-prod**: Combined OS install + ADK middleware package for Engage devices. This package includes system signed ADK middleware components and OS components and can be installed on any Engage device as of a certain OS version. See release notes document for details. This is the basic install package for Engage devices and combines vos2-sys\_all-prod and OS.
* **vos2-engage\_factory-prod**: This package is a clean installation package to restore the OS and ADK on Engage devices to the factory default. It includes the OS and ADK middleware components, mainly to enable remote terminal management on the device. It is a clean installation package and will remove any OS or system signed package already on the device.
* **vos2-base-prod**: This package is a clean installation package to restore the OS and ADK on V/OS2 based base stations to the factory default. It includes the OS and some basic middleware components, mainly to enable remote management on the device. This package will remove any OS or system signed package already on the device prior to installation.
* **vos2-engage\_cpdevkit-prod**: This package is the same as vos2-engage-prod, but for staging CP cloud and none-GUI CP downloader
* **vos-ux-prod**: Combined default ADK middleware + OS install package for V/OS UX devices. This package includes system signed ADK middleware components and OS components and can be installed on UX devices only. This is the basic install package for V/OS UX devices and combines vos-sys\_all-prod and UX OS.

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>Important note for V/OS on UX: If you have installed a newer Secure Boot Installer (SBI) on your device (>= 3.17.0), installing an older version of ADK, which includes an older SBI boot loader, will tamper your device. You can use the dl file "vos-ux_no_sbi-prod" to load an older version in this case, the new SBI is compatible with older OS versions.</p></div>
* **vos-ux\_no\_sbi-prod**: Combined ADK middleware + OS install package for V/OS UX devices but without Secure Boot Installer (SBI) update. Other content is equal to vos-ux-prod. See above warning note about SBI update. Main purpose of this solution is the usage in test environments (e.g. for testing release upgrades). This package is not for use in field!

{% hint style="info" %}
The following packages are depreciated: \[unsupported block]
{% endhint %}

**SDI Solution Install (V/OS, V/OS2):** This type of files is used for a clean system installation like above solutions. In addition, they are containing ADK-SDI server bundles. See ADK-SDI Programmers Guide for more details about ADK-SDI. Note that in ADK 4.6.x and ADK 4.7.x SDI bundles are usr-signed. So below files need to be re-signed with the regional sponsor card.

* **SDI standard (with UI): vos2-sdi\_solution-prod:** Combined OS install + ADK middleware + ADK-SDI package for Engage devices.
* **SDI headless (without UI): vos2-sdi\_hdl\_solution-prod:** Combined OS install + ADK middleware + ADK-SDI package for Engage devices.
* **SDI headless for "Engage Android Subdevices": vos2-sdi\_hdl\_android-prod:** Combined OS install + ADK middleware + ADK-SDI package for "Engage Android Subdevices" like CM5, M440 and M424. For the interaction with Android a special version of the VHQ agent (agt-subdev) is integrated.
* **SDI external PIN pad: vos2-sdi\_epm\_solution-prod:** Combined OS install + ADK middleware + ADK-SDI package for Engage devices. SDI is configured in headless mode. Additional bundles for the configuration of External PinPad (EPP) are included. See ADK-SDI Programmers Guide for more details about EPP configuration and usage.
* **SDI headless for UX (without UI): vos-ux\_sdi\_hdl\_solution-prod:** Combined OS install + ADK middleware + ADK-SDI package for V/OS UX devices.

**VOS3 debug related download files:** VOS3 introduces actual debug images usable for application development, independently from the new appdev signing mechanism. These debug images differ in a few ways from the regular, secure production images, as listed here. Related information can be found in other chapters about application development, installer and key loading. Please note, that the signature mechanism is independent from the debug files, the list specifies the mechanism in brackets.

* (Debug) Modified kernel and other system binary compile options related to debug mechanisms.
* (Debug) Additional debug tools to debug applications, mostly from the command line
* (Debug) Allows changing of individual system components and does not tie down their version in the SLP bundle.
* (Signature) Enabled user login usable from the console
* (Signature) Allows loading of development keys, and other system packages, only
* (Signature) Allows loading of packman signed user packages

These files are available:

* **vos3-\<version>-(neo|vegas|\<device>)-dev**: Installs the same file as the secure, production version above, except the console login is enabled and key loading uses development key packages. As the runtime behavior is assumed to be very close to the production software, this image is intended to be used to verify and test solutions before production signing.
* **vos3-\<version>-(neo|vegas|\<device>)\_debug-dev**: Installs a full package of system debug binaries and adds additional debug tools. It also enables the console login and relies on development signatures, and can be used to debug applications.
* **vos3-\<version>-debug\_tools-dev**: This bundle loads the debug tools on top of another image, without changing the underlying system components. It can be used in cases, where an issue cannot be reproduced with the debug variant. However it may not support all debug related features.

### System Component Installation Download Files <a href="#subsec_syscompinstall" id="subsec_syscompinstall"></a>

**System Component Install (V/OS, V/OS2):** *Use of these files is mostly depreciated, please check below.* These files are used to update a single or a subset of components. Middleware components will only install on older versions and will not clean out the device. OS packages usually remove all other OS and system signed components, which may leave the terminal in an undefined state.

All dependencies need to be resolved when using these kind of files!

* **vos2-sys\_all-prod**: Main package to load system signed ADK middleware components, without the OS. The content of this package is also included in some other solution packages.
* **vos2-engage\_factory\_mw-prod**: Basic ADK middleware system signed components for Engage devices to restore the initial factory status. This package is the same as vos2-engage\_factory-prod but without OS.
* **vos2-base\_factory\_mw-prod**: Basic ADK middleware system signed components for V/OS2 based base station devices to restore the initial factory status. This package is the same as vos2-base-prod but without OS.
* **vos-sys\_all-prod**: Main package to load system signed ADK middleware components, without the OS. The content of this package is also included in some other solution packages.
* **vos-cp-prod**: Enables Commerce Platform features on V/OS terminal units. No OS or other ADK components included in this package.

{% hint style="info" %}
V/OS3 no longer supports mixing and partial update of ADK components that invalidates the released set of components on production mode units. A modified image will not install and will be rejected due to incorrect dependencies.
{% endhint %}

**Component** **Remove:** Packages removing ADK middleware components from a terminal device.

* **vos2-sys\_signed\_remove-prod**: Removes any system signed ADK middleware component from a device with V/OS2. OS and user signed components are not affected by use of this package.
* **vos-sys\_signed\_remove-prod**: Removes any system signed ADK middleware component from a device with V/OS. OS and user signed components are not affected by use of this package.

{% hint style="info" %}
V/OS3 no longer supports removing system components (e.g. MAC, SDI, etc.) by the same mechanism, which locks down component versions. Attempts to remove components, which are required by the system are rejected by the installer. For details, please check the VOS3 installer section in this documentation.
{% endhint %}

## Update Procedure <a href="#sec_update_procedure" id="sec_update_procedure"></a>

Following basic/default install packages for Engage and Trident platform units.

* neo/vegas
  * Load vos3/load/solutions/dl.adk-\<version>-vos3-\<device-type>-prod.tar
* Engage
  * Load vos2/load/solutions/dl.adk-\<version>-vos2-engage-prod.tgz
* Trident (UX only, no support for other Trident devices; support for MX and VX stopped with ADK 4.6)
  * Load vos/load/solutions/dl.adk-\<version>-vos-ux-prod.tgz

In general, see the ADK Release Notes document for release specific update procedures.

## System Upgrade Troubleshooting <a href="#sec_upgrade_troubleshooting" id="sec_upgrade_troubleshooting"></a>

### Ux115 & ADK 4.8.x Upgrade Troubleshooting <a href="#subsec_ux115_upgrade_troubleshooting" id="subsec_ux115_upgrade_troubleshooting"></a>

This section describes a solution and workaround for CIB / Backlight BSOD issue on Ux115 (supported starting from ADK 4.8).

If a Ux115 device is flashed or factory installed with any version less than ADK 4.8.6, then device MUST have dl.cib update package installed before installing ADK version upgrade from sysmode.

{% hint style="info" %}
Please ask the Support team for dl.cib package.
{% endhint %}

{% hint style="warning" %}
If the upgrade was done without the dl.cib package installed, the device will have a black screen on boot, but in fact, the device is working. The display backlight is turned off and hence the device appears bricked. If the device is connected to the VHQ or other TMS, it is possible to install dl.cib update and fix it.
{% endhint %}

#### Upgrade instructions <a href="#subsec_ux115_upgrade_troubleshooting_instructions" id="subsec_ux115_upgrade_troubleshooting_instructions"></a>

Using the USB memory stick:

* Download the dl.cib file and copy it to a USB flash memory stick
* Attach the USB device to the USB port 2 on Ux115
* Go to the Sysmode> Update> USB Memory, and select the dl.cib file for installation
* Reboot the device
* Install, load any ADK release> = 4.8.1 as dl buildalls package from USB device in the same way.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sandbox-docs.verifone.com/adk-5.0-programmers-guide/readme/developing_applications/pg_all_packages.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.