VOS3 Foreign Object Detection (FOD)

Introduction

The FOD (Foreign Object Detector) is a VOS3 solution that consolidates different PinPad overlay detection mechanisms in one place and processes overlay detection tests using the common FOD application.

Different device models may have different sensors to help detect the keypad overlay.

On M450-A and M425-A VOS3 devices (also Plus variations of these devices), there is an embedded proximity sensor that emits horizontally across the keypad area and can detect the keypad overlay.

On older VOS2 devices, such as M440, M425, M400, a different solution was used - an Anti-skimming device (a probe/card) that is inserted in the card reader to measure the card slot's thickness and report an overlay if the returned value differs from the expected one. This mechanism has also been ported to VOS3 and is supported on M450, M425, M450-A, M425-A devices, as they have the same card slot thickness

Check the VOS2 solution user's guide for more details about the Anti-skimming probe test implementation.

So, today, the FOD solution on VOS3 provides the following overlay detection tests:

#	Solution	Device models	Platform	Tests
1	P-sensor tests	M450-A, M425-A	VOS3	Scheduled Automatic tests; Automatic tests invoked by a user application; Manual tests on demand via MAC CP
2	Probe tests	M450, M425, M450-A, M425-A	VOS3	Manual tests on demand via MAC CP

The FOD application on VOS3 does not install automatically with the ADK/VOS3 release, and the FOD application DL should be installed on top. Please get in touch with the Support team for the proper installation file!

The very first use and the Re-Calibration of the P-sensor

Below is the instruction for proper P-sensor use and the first installment on the device to set up a "No Skimmer" baseline. The recalibration option is available in the MAC CP → FOD → Configuration menu (read the "Configuration menu" chapter below for more details):

• Device installation should avoid direct sunlight, or being too close to a window with sunlight, or a direct halogen spotlight.
• After device installation, each device should perform a "FOD Re-Calibration" to establish a good "No Skimmer" baseline.
• The Overlay detection algorithm is embedded in the system and is not changeable by a user or application.​
• When an Overlay is detected, the user can check the device physically whether it is a real overlay or a false alarm.
• If it is indeed a false alarm, the user can perform the "FOD Re-Calibration" operation to force the device to establish a new "No Skimmer" baseline to prevent further false alarms.

Care should be taken when cleaning the device. Contamination close to the p-sensor opening should be removed carefully, and no foreign object should intrude into the p-sensor opening.

FOD Control Panel

The FOD Control Panel is the System application that can be installed on the MAC desktop by the customer on demand or is included in the ADK release (newer releases).

The FOD Control Panel Main menu contains the configuration of tests, test logs and the Overlay detection test running menu:

Access control

FOD Control Panel functions can be protected by a password, according to the common password policy on the device (defined by the Customer).

The FOD menu/operations are protected by the following access groups:

Menu	Operation	Access group
Logs	All operations in the "Logs" menu	System_viewer
Overlay Detection	All operations in the "Overlay detection" menu	System_editor
Configuration
	All except the Re-calibration operation	System_editor
	Re-calibration	SEC_editor

According to the password policy, if the "System_viewer", "System_editor" or "SEC_editor" access groups are tied to a password (e.g. Supervisor), the system will require authentication when the user try to perform a protected operation.

The Re-calibration option is under the "SEC_editor'' access group as this operation can damage p-sensor tests if done in an improper environment. The "SEC_editor" is usually protected by a password.

Configuration menu

In this menu, the user can set the FOD configuration. By default, all settings are disabled.

Automatic mode:

• If enabled, the automatic tests will run according to the configuration in the interval given in the field "Interval". The interval is specified in minutes, valid range: 1–1380 (up to 23 hours).

Schedule test:

• If enabled, the automatic test will be scheduled at the time set in the ''Schedule test time'' field.

VHQ

• Autotesting report to VHQ

  • if enabled, then test log data will be automatically reported to VHQ
• UI test report to VHQ (config values: 0 = disabled, 1 = always report, 2 = user select)

  • if 1 (enabled), then right after the test data will be automatically reported to VHQ
  • if 2 (''User select''), then right before the test, the UI prompt with the "Report result to VHQ? Yes/No" will be displayed

MAC

• Send Notification

  • if enabled, then a new MAC notification will be generated and the UI message will be displayed if a Foreign object is detected in the keypad area. The MAC Notification then will be displayed in the status bar, and also available in the Notifications Control Panel.

    • "Cancel" - to close the message
    • "Clear" - to clear (delete) the MAC notification

Storage

• the amount of logs stored in the database

Re-Calibration

• Recalibrates the p-sensor baseline. The FOD daemon maintains three baseline levels:

  • FCB (Factory-Calibration Baseline) — derived from factory calibration data on first run; never changes.
  • PIB (Post-Installation Baseline) — set by Re-Calibration; computed as the average of FCB and the current proximity reading. Reset each time the operator performs Re-Calibration.
  • Daily Baseline — adjusted automatically after each PCI reboot (within 30 minutes of reboot time) to compensate for slow environmental drift. Only updated when no overlay is detected and readings are within expected bounds.

Default configuration values (applied when no user config file is present):

Field	Default	Valid values	Description
auto_mode	0	0 or 1	Enable periodic automatic p-sensor tests at fixed interval.
interval	60	1–1380 (minutes)	Interval between automatic tests.
schedule_test	0	0 or 1	Enable a single daily test at a fixed time.
schedule_time	"12:00:00"	HH:MM:SS string	Time of day for the scheduled test (local device time).
max_log	2000	Any positive integer	Maximum log entries kept per table in the database.
report_to_vhq	0	0 or 1	Automatically report automatic test results to VHQ.
report_to_vhq_ui	0	0, 1, or 2	0 = disabled; 1 = always report after manual test; 2 = prompt user before reporting.
notify_mac	0	0 or 1	Generate a critical MAC notification when an overlay is detected.

All changes will take effect after the device is rebooted:

Remote configuration

All settings listed above can be configured by loading a user-signed config file. The example of configuration:

{     
    "auto_mode":0,
    "interval":5,     
    "max_log":2000,     
    "report_to_vhq":0,     
    "schedule_test":0,     
    "report_to_vhq_ui":0,     
    "notify_mac":0,     
    "schedule_time":"12:00:00" 
}

Configuration field notes:

• interval: value in minutes, valid range 1–1380.
• report_to_vhq_ui: 0 = disabled, 1 = always report after manual test, 2 = prompt user before reporting.

The example of packaging (check the Packman user's guide for more details about the packaging and signing):

$(vos3_PACK_SCRIPT) \
         --dest $@/$(vos3_PACKAGE_NAME).tar \         
         --bndlname $(NAME) \         
         --pkgname $(NAME) \         
         --version $(VERSION) \         
         --user usr1 \         
         --group share \         
         --type versioned_data \         
         --permission 777 \         
         --umask 002 \         
         config.json=config.json

Manual P-sensor tests

P-sensor tests detect the pinpad overlay by the proximity sensor that emits horizontally across the keypad area.

Tests can be scheduled or automatic according to the configuration.

To run P-sensor test manually, the user needs to enter the "Overlay detection" menu and select the "Test proximity sensor".

The system will start the test and return the overlay status: "Overlay detected!" or "No overlay"

Note: The p-sensor test can return four possible outcomes:

• No overlay — test passed, no foreign object detected.
• Overlay detected! — a foreign object is detected in the keypad area.
• Sun-light too strong — ambient light exceeded the sensor threshold. This is not an overlay detection. Move the device away from direct sunlight or strong artificial light and re-run the test.
• Variation Out-Of-Range — sensor readings were too unstable to produce a reliable result. The test retries automatically up to 5 times with 5-second pauses between attempts. If readings remain unstable, this result is recorded (result code 2). Common causes: vibration, nearby movement, or a hardware issue near the sensor. Re-run the test on a stationary device.

Test results will be stored in FOD Proximity Sensor Logs where:

• The most recent section shows the latest log entry;
• The "Recent fails'' section shows all failed logs (the number of logs according to the configuration)

The failed log is the test result that doesn't return "No overlay".

To see detailed information about the test result, need to select the log entry:

Manual Probe tests

The Probe test is only manual, and requires the use of the Anti-skimming device (a probe/card) that must be inserted in the card reader before the test.

To run the Probe test manually, the user needs to enter the "Overlay detection" menu and select the "Test probe".

The system will start the test and return the overlay status: "Overlay detected!" or "No overlay"

The probe test takes approximately 10 seconds to complete. The call is asynchronous — it returns Result::Ok immediately and the result is stored in the log database when the test finishes. Retrieve results with fod_get_probe_check_logs().

Test results will be stored in FOD Probe Logs.

Automatic P-sensor tests

Automatic p-sensor tests can be initiated either by Automatic configuration of test running, or by the API call.

The Automatic test configuration is described in the "Configuration menu" chapter.

The customer needs to set the automatic test during a non-transaction period (user finger or card movements can return false-positive Overlay detection results as they will be sensed by the p-sensor).

If the automatic test returns the "Overlay detected", the user should check the physical appearance of the device. It is up to the application to stop transactions or show an error message on the screen if the overlay is detected.

Below is the description of the external API to run p-sensor tests that can be used by an application.

Note on TestReason parameter: Applications must always pass TestReason::NORMAL to fod_psensor_check(). The DAILY and RECALIBRATION values are reserved for the sys_fod system process and return AccessRestricted when called from a regular application.

Both fod_psensor_check() and fod_probe_check() are asynchronous. The return value of these calls only tells you whether the test thread was successfully started:

• Result::Ok — test thread started. The test is now running in the background.
• Any other code (e.g. PsensorAbsent, PsensorTestInProgress, PsensorBaselineNotSet) — test did not start. See the Return Codes table for the cause.

The actual overlay detection outcome is never returned by fod_psensor_check() directly. It is written to the log database when the test finishes. To retrieve it: poll fod_psensor_status() (every 2–3 seconds — see note below) until it no longer returns PsensorTestInProgress, then call fod_get_psensor_check_logs().

enum class Result
{
	Ok = 0,
	BadParameter,
	SockCreateErr,
	SockUnlinkErr,
	SockOpenErr,
	SockWriteErr,
	SockReadErr,
	InvalidJSON,
	BadOutputFile,
	ProbeAbsent,
	PsensorAbsent,
	ProbeCommunicationErr,
	PsensorCommunicationErr,
	ProbeTestInProgress,
	PsensorTestInProgress,
	PsensorBaselineNotSet,
	AccessRestricted
};
enum class TestReason{
	NORMAL = 0,
	DAILY,
	RECALIBRATION
};
/**
 * Set configuration for Foreign Object Detector
 * @param[in] config_js - JSON object
 * @return Operation result
 */
FOD_API Result fod_set_config( const vfiipc::JSObject &config_js );
/**
 * Get configuration for Foreign Object Detector
 * @param[out] config_js - JSON object
 * @return Operation result
 */
FOD_API Result fod_get_config( vfiipc::JSObject &config_js );
/**
 * Start foreign object detection probe test
 * @param[in] report_to_vhq - report results to VHQ agent
 * @return Operation result
 */
FOD_API Result fod_probe_check( bool report_to_vhq = false );
/**
 * Start foreign object detection Proximity sensor test
 * @param[in] report_to_vhq - report results to VHQ agent
 * @param[in] reason - must be Normal for regular use
 * @return Operation result
 */
FOD_API Result fod_psensor_check( bool report_to_vhq = false, TestReason reason = TestReason::NORMAL );
/**
 * Dump foreign object detection probe tests results to the file
 * @param[out] file_path - output file path
 * @return Operation result
 */
FOD_API Result fod_get_probe_check_logs( std::string &file_path );
/**
 * Get Proximity sensor status
 * @return Operation result[OK, absent, in progress]
 */
FOD_API Result fod_psensor_status();
/**
 * Dump foreign object detection Proximity sensor tests results to the file
 * @param[out] file_path - output file path
 * @return Operation result
 */
FOD_API Result fod_get_psensor_check_logs( std::string &file_path );
/**
 * Foreign object detection probe tests results in json object
 * @param[out] records - json object array with records
 * @return Operation result
 */
FOD_API Result fod_get_probe_check_logs( vfiipc::JSObject &records );
/**
 * Foreign object detection Proximity sensor tests results in json object
 * @param[out] records - json object array with records
 * @return Operation result
 */
FOD_API Result fod_get_psensor_check_logs( vfiipc::JSObject &records );
/**
 * Dump foreign object detection Proximity sensor baseline logs to the file
 * @param[out] file_path - output file path
 * @return Operation result
 */
FOD_API Result fod_get_baseline_logs( std::string &file_path );
/**
 * Foreign object detection Proximity sensor baseline logs in json object
 * @param[out] records - json object array with records
 * @return Operation result
 */
FOD_API Result fod_get_baseline_logs( vfiipc::JSObject &records );

Log record fields

The log records returned by fod_get_psensor_check_logs() and fod_get_probe_check_logs() contain the following fields. Understanding the difference between status, result, and vhq_status is important:

P-sensor log fields

Field	Type	Description
result	integer	The overlay detection outcome: -1 = test did not complete (communication error); 0 = no overlay; 1 = overlay detected; 2 = Variation Out-Of-Range (readings too unstable after all retries).
status	integer	The infrastructure result (Result enum value): reflects whether the sensor communication worked, not whether an overlay is present. 0 (Ok) means the sensor was read successfully; 12 (PsensorCommunicationErr) means the sensor data read failed.
vhq_status	integer	Result of the VHQ report submission: -1 = VHQ reporting was not requested, or VHQ is unavailable on this device; 0 = report sent successfully; other values = TMS error code from tms_sendCustomAppEvent().
description	string	Human-readable outcome: "No overlay", "Overlay detected!", "Sun-light too strong", "Variation Out-Of-Range", or "Bad sensor data".
label	string	"System-Poll" = test started by the auto/scheduled mechanism; "User-Poll" = test started by a user application.
RIR_max, RIR_min, RIR_average	integer	Proximity sensor (infrared reflectance) reading statistics across the measurement window. Useful for diagnosing borderline or unstable results.
AIR_average	integer	Ambient light sensor average. Values above 150 000 trigger the "Sun-light too strong" result.
baseline	integer	The daily baseline value in effect when the test ran. Stored for traceability.
b1	integer	Needed for diagnosing borderline or unstable results.
local_time, timestamp	string / integer	Local time string and Unix timestamp of the test.

Probe log fields

Field	Type	Description
status	integer	Combines infrastructure and detection outcome for probe tests: 0 (Ok) = no overlay; 11 (ProbeCommunicationErr) = sensor read failed; any other non-zero value = ICC skimmer error code indicating overlay or hardware issue. Note: probe tests have no separate result field — status is the authoritative outcome.
vhq_status	integer	Same as p-sensor: -1 if not sent, 0 if sent successfully, otherwise TMS error code.
description	string	"No overlay detected" or "Overlay detected!" or an error description.
SN	string	Serial number of the anti-skimming probe card used in the test.

API Return Codes Reference

All API functions return a value from the Result enum. The table below explains each code and the recommended action:

Code	Value	Meaning	Recommended action
Ok	0	Success. For fod_psensor_check() / fod_probe_check(): the test thread was started, not completed.	—
BadParameter	1	Invalid or malformed parameter.	Validate input JSON.
SockCreateErr, SockUnlinkErr, SockOpenErr, SockWriteErr, SockReadErr	2–6	IPC socket error communicating with the FOD daemon.	Verify the FOD daemon is running.
InvalidJSON	7	Config JSON is syntactically invalid.	Validate JSON format and field names.
BadOutputFile	8	Cannot write the log output file.	Check filesystem permissions.
ProbeAbsent	9	Probe sensor not available on this device.	Check device compatibility table.
PsensorAbsent	10	Proximity sensor not available on this device.	Check device compatibility; call fod_psensor_status() first.
ProbeCommunicationErr	11	Probe sensor data read error.	Ensure probe card is fully inserted; retry.
PsensorCommunicationErr	12	Proximity sensor data read error.	Retry; check device health.
ProbeTestInProgress	13	A probe test is already running.	Wait for the current test to finish before starting a new one.
PsensorTestInProgress	14	A p-sensor test is already running.	Poll with fod_psensor_status() until it returns Ok.
PsensorBaselineNotSet	15	No p-sensor calibration baseline exists.	Perform Re-Calibration from MAC CP → FOD → Configuration.
AccessRestricted	16	Calling process is not authorized. Returned when a non-sys_fod process uses TestReason::DAILY or RECALIBRATION.	Use TestReason::NORMAL.

fod_psensor_status() return values

This function reports the current state of the proximity sensor. It is the recommended way to check readiness before starting a test, and to poll for completion after one:

• Ok — sensor present, idle, baseline set. Safe to start a test.
• PsensorAbsent — proximity sensor not available on this device model.
• PsensorTestInProgress — a test is currently running.
• PsensorBaselineNotSet — sensor present but not calibrated. Perform Re-Calibration first.

Polling frequency: when waiting for a test to finish, call fod_psensor_status() no more than once every 2–3 seconds. The call communicates with the FOD daemon over a Unix socket; polling faster than this is wasteful and puts unnecessary load on the system without providing any benefit, as test results are not available at sub-second granularity.

P-sensor Test Polling Flow

The following diagram illustrates the recommended application-side flow for running a p-sensor test and retrieving the result. Because fod_psensor_check() is asynchronous, the caller must poll fod_psensor_status() to detect completion.

Key File Paths

Useful for troubleshooting and deployment:

Path	Description
/mnt/appdata/versioned/usr1/config.json	User-supplied FOD configuration. If present, overrides the system defaults. Deploy via Packman (see Remote configuration).
/mnt/sysdata/versioned/sys_fod/config.json	System default FOD configuration.
/mnt/sysdata/versioned/sys_fod/log.db	SQLite database with all p-sensor, probe, and baseline log entries.
/mnt/sysdata/versioned/sys_fod/baseline.json	P-sensor calibration baseline (FCB, PIB, daily values). Deleted or reset by Re-Calibration.
/persist/sensors/registry/registry/sip3510_platform.prox.fac_cal	Factory calibration data. Used on first run to bootstrap the baseline when baseline.json does not exist.
/tmp/fod.sock	Unix domain socket for IPC between the API library and the FOD daemon.

Known limitations

Avoid p-sensor test running right after the reboot, as it requires the system to load and establish the p-sensor configuration. Keep at least 20 seconds between the reboot and the p-sensor test.

First test after daemon start-up may be slightly inconsistent. The proximity sensor hardware needs a short stabilisation period after the daemon initialises. The very first test run (particularly on a freshly installed or recently rebooted device) may produce unstable readings and trigger a "Variation Out-Of-Range" result. If this happens, wait a few seconds and re-run the test — subsequent tests on a stabilised sensor will be reliable. This is expected behaviour and does not indicate a hardware fault.

If the new configuration is set via API, the device needs to be rebooted to apply the new config (e.g. enable/disable automatic tests).

FAQ

The p-sensor test returns "Sun-light too strong". Is the device compromised?

No. This result means the ambient light level exceeded the sensor threshold and the test could not produce a reliable reading. It does not indicate an overlay. Move the device away from direct sunlight or strong artificial light and re-run the test.

fod_psensor_check() returns PsensorBaselineNotSet. What should I do?

The device has not been calibrated yet. Perform "FOD Re-Calibration" from MAC CP → FOD → Configuration to establish a baseline. Ensure the device is in proper lighting conditions (no direct sunlight) during calibration.

The test returns "Overlay detected" but the device looks clean. What should I do?

This is likely a false alarm caused by environmental changes (new lighting conditions, device relocation, or contamination near the p-sensor opening). Perform "FOD Re-Calibration" from MAC CP → FOD → Configuration to establish a new "No Skimmer" baseline.

Can my application use TestReason::DAILY or TestReason::RECALIBRATION?

No. These values are reserved for the sys_fod system process. Calling fod_psensor_check() with these reasons from a regular application returns AccessRestricted. Always use TestReason::NORMAL.

I called fod_set_config() but the auto-test is not running. Why?

Configuration changes (enabling/disabling auto tests, changing interval, etc.) require a device reboot to take effect.

Can probe tests be scheduled or automated?

No. Probe tests are manual-only and require the Anti-skimming probe card to be physically inserted in the card reader before starting the test.

How do I check whether the p-sensor is available on the current device?

Call fod_psensor_status() before running a test. It returns Ok (sensor ready and baseline set), PsensorAbsent (sensor not available on this device model), PsensorTestInProgress (a test is already running), or PsensorBaselineNotSet (sensor present but not yet calibrated — perform Re-Calibration first).

What does "Variation Out-Of-Range" mean in the p-sensor logs?

The sensor readings were too unstable to produce a reliable result. The test retries up to 5 times with 5-second pauses. If readings remain unstable after all retries, "Variation Out-Of-Range" is recorded (result code 2). This is not an overlay detection. Common causes: device vibration, nearby movement, or a hardware issue near the sensor. Re-run the test on a stationary device.

fod_psensor_check() returned Ok but there is no test result yet. Is that expected?

Yes. fod_psensor_check() is asynchronous: it starts the test in a background thread and returns Result::Ok immediately. The result is only available in the log database after the test completes. Poll fod_psensor_status() until it no longer returns PsensorTestInProgress, then call fod_get_psensor_check_logs() to retrieve the result.

What is "Baseline drift out of range" in the baseline logs?

This critical warning is logged during the automatic daily baseline check (triggered within 30 minutes after each PCI reboot). It means the proximity reading during the daily check exceeded the expected drift threshold, indicating the device environment changed significantly or a real overlay may be present. Physically inspect the device. If it is clean, perform Re-Calibration to re-establish the baseline.

Can auto_mode and schedule_test be enabled at the same time?

Yes. If both are enabled, the FOD daemon runs two independent test series: a periodic test at the configured interval, and a single daily test at the scheduled time. Both use TestReason::NORMAL and the report_to_vhq setting applies to both.

How long does a p-sensor test take? What are the minimum and maximum expected durations?

The p-sensor test is asynchronous. In the fast path (no retries needed), it completes in approximately 2–3 seconds. If the sensor readings are unstable (Variation Out-Of-Range), the test retries up to 5 times with 5-second pauses between attempts. The maximum expected duration is approximately 45 seconds (6 polling attempts). If the test is still running after ~45 seconds, check device health or retry later.