Configuration Details

Overview

This guide explains how to configure your document scanner using the config.yml file. The configuration file uses YAML format and controls all aspects of the scanner’s behavior, from logging to MRZ parsing, NFC reading, and output formatting.

Configuration File Location

The configuration file should be named config.yml and placed in the same directory as the scanner application. A template file (config.template.yml) is provided as a starting point.

System Settings

Controls logging and debug output for troubleshooting.

system:
  debug: false
  tofile: false
  filename: ./logs/log.txt
  loglevel: 5
  sourceinfo: false

Configuration Options

Log Levels

Choose the appropriate log level based on your needs:

• 0 - Verbose: Everything including detailed trace information
• 1 - Debug: Debug messages and above
• 2 - Info: Informational messages and above
• 3 - Warning: Warnings and errors only
• 4 - Error: Errors only
• 5 - Off: No logging

Recommended Settings:

• Production: loglevel: 3 (Warning)
• Development: loglevel: 1 (Debug)
• Troubleshooting: loglevel: 0 (Verbose) with debug: true

MRZ Settings

Configures Machine Readable Zone parsing behavior.

mrz:
  autocleanparts: true
  usecorrector: false
  ignorefillerchecksnonzero: true
  allowexperimentalparsers: true
  addextendedinfo: true
  addchecksinfo: true
  agetop: 18
  agebottom: 16
  translateids: false
  outputformat: TEXT

Configuration Options

Understanding Auto Clean and Corrector

Auto Clean Parts (autocleanparts: true)

• Removes filler characters (<) from parsed values
• Example: SMITH<<JOHN< becomes SMITH JOHN
• Recommended: Keep enabled for cleaner output

Use Corrector (usecorrector: false)

• Attempts to fix common OCR errors (0→O, 1→I, etc.)
• May introduce false corrections in some cases
• Recommended: Start with disabled, enable if experiencing consistent OCR issues

Age Verification

The agetop and agebottom settings define age ranges for validation:

agetop: 18 # Must be under 18 years old
agebottom: 16 # Must be over 16 years old

Common use cases:

• Alcohol sales: agetop: 999, agebottom: 21
• Minor verification: agetop: 18, agebottom: 0
• Senior discount: agetop: 999, agebottom: 65

Serial Port Settings

Configures communication with the scanner hardware via serial connection.

serial:
  preferredportname: ""
  preferredvidpid: ""
  properties:
    baudrate: 115200
    databits: 8
    stopbits: 0
    parity: 2
    timeout: 0s

Configuration Options

Port Auto-Detection

Leave preferredportname and preferredvidpid empty for automatic detection:

preferredportname: "" # Auto-detect
preferredvidpid: "" # Auto-detect

Specifying a Port

Windows:

preferredportname: "COM4"

Linux/Mac:

preferredportname: "/dev/ttyUSB0"

Using Vendor/Product ID

If multiple serial devices are connected, specify the exact device:

preferredvidpid: "0403:6001" # FTDI USB Serial

Note: Most users can leave serial settings at their defaults. Only modify if experiencing connection issues.

IO Modules

Configures external input/output relay modules — for example to switch lights, gates, or buzzers based on the outcome of a scan, such as turning on a green light when an age check passes and a red light when it fails.

iomodules:
  enabled: false
  baseactions:
    - id: ageok
      title: Age OK
      description: Indicates that the age is above the specified threshold
    - id: agebetween
      title: Age Between
      description: Indicates that the age is between the specified thresholds
    - id: agefail
      title: Age Fail
      description: Indicates that the age is below the specified threshold
    - id: overallok
      title: Overall OK
      description: Indicates that all checks have passed successfully
    - id: overallfail
      title: Overall Fail
      description: Indicates that one or more checks have failed
  actions:
    - baseactionid: ageok
      channel: 1
      enabled: true
      switchtype: 2
      pulseduration: 1000

Main Configuration

Base Actions

baseactions describe the conditions that can trigger a switch — they are templates, not switched directly. Each one has an id that you reference from actions.

The built-in condition ids are:

You generally don’t need to modify baseactions — just reference the built-in ids from your actions.

Actions

actions connect a base action (a condition) to a physical output channel and define how that channel should switch when the condition occurs.

Example: Age Verification Gate with Indicator Lights

iomodules:
  enabled: true
  actions:
    - baseactionid: ageok
      channel: 1 # green light
      enabled: true
      switchtype: 2
      pulseduration: 2000
    - baseactionid: agefail
      channel: 2 # red light
      enabled: true
      switchtype: 2
      pulseduration: 2000

Output Settings

Configures how and where scan results are saved or sent.

output:
  enabled: false
  outputitems:
    - name: File
      format: TEXT
      config:
        file_name: <time>-<doccode>-<issuer>
        file_path: ./
    - name: URL
      format: JSON
      config:
        url: https://localhost

Main Configuration

Output Item Types

File Output

Save scan results to local files.

- name: File
  format: TEXT # TEXT, JSON, or XML
  config:
    file_name: <time>-<doccode>-<issuer>
    file_path: ./scans/

File Name Templates:

Use placeholders to create dynamic file names:

Example file names:

• <time>-<doccode>-<issuer> → 20231215-143022-P-USA.txt
• <docnum>-<name_last> → AB1234567-SMITH.json
• scan-<time> → scan-20231215-143022.xml

URL Output

Send scan results to a web service via HTTP POST.

- name: URL
  format: JSON # TEXT, JSON, or XML
  config:
    url: https://api.example.com/scans

The scanner will POST the scan results to the specified URL in the chosen format.

Multiple Output Destinations

You can configure multiple outputs simultaneously:

output:
  enabled: true
  outputitems:
    - name: File
      format: JSON
      config:
        file_name: <time>-scan
        file_path: ./backup/
    - name: URL
      format: JSON
      config:
        url: https://api.example.com/scans
    - name: File
      format: TEXT
      config:
        file_name: <docnum>-readable
        file_path: ./reports/

Server Settings

Configures the built-in web server for live monitoring and control.

server:
  enabled: true
  port: 8080
  rootfolder: ./www
  autoopen: true
  wscors:
    enabled: false
    trustedorigins:
      - http://localhost:8080
  httpcors:
    enabled: false
    trustedorigins:
      - localhost
      - 127.0.0.1

Configuration Options

WebSocket CORS Settings

Controls WebSocket cross-origin access for real-time updates.

wscors:
  enabled: false # Enable WebSocket CORS
  trustedorigins: # List of allowed origins
    - http://localhost:8080
    - http://192.168.1.100:8080

Security Note: WebSocket CORS can be disabled in trusted local networks. Enable it when:

• Accessing the scanner from different computers
• Using custom web interfaces
• Exposing the scanner to external networks

HTTP CORS Settings

Controls HTTP API cross-origin access.

httpcors:
  enabled: false # Enable HTTP CORS
  trustedorigins: # List of allowed origins
    - localhost
    - 127.0.0.1
    - 192.168.1.100

When to Enable CORS:

• Local network only, same computer: Keep disabled (default)
• Local network, multiple computers: Enable and add all computer IPs to trustedorigins
• External access: Enable with specific domains only

Example: Multi-Computer Setup

server:
  enabled: true
  port: 8080
  autoopen: false # Don't auto-open on server
  wscors:
    enabled: true
    trustedorigins:
      - http://192.168.1.50:8080 # Scanner computer
      - http://192.168.1.100:8080 # Client computer 1
      - http://192.168.1.101:8080 # Client computer 2
  httpcors:
    enabled: true
    trustedorigins:
      - 192.168.1.50
      - 192.168.1.100
      - 192.168.1.101

NFC Settings

Configures NFC chip reading for electronic documents (e-passports, e-ID cards).

nfc:
  enabled: true
  inittimeout: 500
  dumpraw: false
  dumprawfolder: ./rawnfcfiles
  readphoto: true
  apdulog: false
  apdulogfile: ./apdu.log.json
  loadspecimencsca: false
  reading:
    smartagemode: false
    accessmode: secure
  images:
    convertjp2: true
    quality: 75
  output:
    simpledatalist: true
    simpleimagelist: true
    fullinfo: false
    parsedlist: true
  skipparts:
    skippa: false
    skipaa: false
    skipca: false
    skippace: false

Main Configuration

Reading Options

reading:
  smartagemode: false
  accessmode: secure

Smart Age Mode:

• Useful for age-restricted scenarios (alcohol sales, age gates)
• Reads minimal data needed to verify age
• Significantly faster than full chip reading
• Does not read photos or other biometric data

When to use:

• Age verification is the only requirement
• Speed is critical
• Don’t need full document verification

Access Mode:

• secure — runs the full set of security checks for the most reliable, tamper-resistant read (recommended for verification scenarios)
• fast — skips some of the slower security steps to read the chip more quickly, at the cost of some assurance

Image Processing

images:
  convertjp2: true
  quality: 75

Image Quality Guidelines:

• 50-60: Low quality, small files (suitable for thumbnails)
• 75: Good balance of quality and size (recommended)
• 85-95: High quality, larger files (archival purposes)
• 100: Maximum quality, very large files

Note: JPEG2000 conversion requires ImageMagick to be installed on your system. Download from: https://imagemagick.org/script/download.php

Output Options

Controls what data is included in NFC scan results.

output:
  simpledatalist: true
  simpleimagelist: true
  fullinfo: false
  parsedlist: true

Recommended Settings:

Fast, minimal output:

simpledatalist: true
simpleimagelist: false
fullinfo: false
parsedlist: true

Complete verification:

simpledatalist: true
simpleimagelist: true
fullinfo: true
parsedlist: true

Age verification only:

simpledatalist: true
simpleimagelist: false
fullinfo: false
parsedlist: false
reading:
  smartagemode: true

Skip Parts

Allows skipping specific authentication steps during NFC reading. Skipping steps can speed up reading, but at the cost of the security guarantees that step provides.

skipparts:
  skippa: false
  skipaa: false
  skipca: false
  skippace: false

When to skip parts:

• Only skip a part if you understand what it verifies and your use case doesn’t depend on that guarantee (e.g. quick informational reads where document authenticity isn’t critical)
• Recommended: leave all parts enabled (false) for verification and border-control scenarios

Custom Fields

Add custom metadata to scan results for tracking and organization.

customfields:
  scannerid: 123456789
  location: Harderwijk
  country: NLD

Custom fields are included in all scan outputs and can contain any information you need. Common uses:

Location Tracking:

customfields:
  location: "Reception Desk"
  building: "Building A"
  floor: 2

Device Management:

customfields:
  scannerid: "SCAN-001"
  department: "Security"
  operator: "John Smith"

Business Logic:

customfields:
  purpose: "Age Verification"
  service_type: "Alcohol Sales"
  pos_id: "REGISTER-5"

You can add as many custom fields as needed. All values must be strings, numbers, or booleans.

Configuration Examples

Example 1: Simple Local Setup

Basic configuration for local use with minimal logging:

system:
  debug: false
  loglevel: 3

mrz:
  autocleanparts: true
  usecorrector: false
  addextendedinfo: true
  addchecksinfo: true

server:
  enabled: true
  port: 8080
  autoopen: true
  wscors:
    enabled: false
  httpcors:
    enabled: false

nfc:
  enabled: true
  readphoto: true
  images:
    quality: 75
  output:
    simpledatalist: true
    simpleimagelist: true
    fullinfo: false
    parsedlist: true

output:
  enabled: false

Example 2: Age Verification Kiosk

Optimized for fast age verification:

system:
  loglevel: 3

mrz:
  autocleanparts: true
  agetop: 999
  agebottom: 21
  addchecksinfo: true

nfc:
  enabled: true
  readphoto: false
  reading:
    smartagemode: true
  output:
    simpledatalist: true
    simpleimagelist: false
    fullinfo: false
    parsedlist: false

server:
  enabled: true
  autoopen: true

customfields:
  location: "Store #1234"
  purpose: "Alcohol Sales"

Example 3: Border Control / Security

Full verification with archival:

system:
  debug: false
  tofile: true
  filename: ./logs/border-log.txt
  loglevel: 2

mrz:
  autocleanparts: true
  usecorrector: true
  allowexperimentalparsers: true
  addextendedinfo: true
  addchecksinfo: true

nfc:
  enabled: true
  dumpraw: true
  dumprawfolder: ./archive/nfc-raw
  readphoto: true
  images:
    quality: 95
  output:
    simpledatalist: true
    simpleimagelist: true
    fullinfo: true
    parsedlist: true

output:
  enabled: true
  outputitems:
    - name: File
      format: JSON
      config:
        file_name: <time>-<doccode>-<docnum>
        file_path: ./archive/scans/
    - name: URL
      format: JSON
      config:
        url: https://border-control-api.gov/scans

customfields:
  checkpoint: "Border Crossing A"
  officer_id: "BC-12345"
  country: "NLD"

Example 4: Development and Testing

Maximum logging and debugging:

system:
  debug: true
  tofile: true
  filename: ./logs/debug-<time>.txt
  loglevel: 0
  sourceinfo: true

mrz:
  autocleanparts: true
  usecorrector: true
  allowexperimentalparsers: true
  addextendedinfo: true
  addchecksinfo: true

serial:
  preferredportname: "COM4"

nfc:
  enabled: true
  dumpraw: true
  apdulog: true
  loadspecimencsca: true
  output:
    fullinfo: true

server:
  enabled: true
  autoopen: true

output:
  enabled: true
  outputitems:
    - name: File
      format: JSON
      config:
        file_name: test-<time>
        file_path: ./test-output/

Troubleshooting

Scanner Not Connecting

Check serial port settings:

serial:
  preferredportname: "" # Try leaving empty for auto-detect

Windows users: Check Device Manager for the correct COM port
Linux users: Check /dev/ for ttyUSB* or ttyACM* devices

Slow NFC Reading

Disable features you don’t need:

nfc:
  readphoto: false # Skip photo if not needed
  output:
    fullinfo: false # Don't read all Data Groups
    simpleimagelist: false

Enable smart age mode:

nfc:
  reading:
    smartagemode: true

Web Interface Not Opening

Check port availability:

server:
  port: 8080 # Try 8081, 8082, etc. if 8080 is in use

Manually open browser:

• Navigate to: http://localhost:8080

Output Files Not Created

Enable output:

output:
  enabled: true # Must be true

Check file path:

outputitems:
  - name: File
    config:
      file_path: ./scans/ # Make sure folder exists

CORS Errors in Browser

Enable CORS for network access:

server:
  wscors:
    enabled: true
    trustedorigins:
      - http://your-ip:8080
  httpcors:
    enabled: true
    trustedorigins:
      - your-ip

Best Practices

Security

1. Never enable specimen CSCA in production

   nfc:
     loadspecimencsca: false # Always false in production!

2. Keep NFC authentication parts enabled

   nfc:
     reading:
       accessmode: secure # Don't use 'fast' unless you understand the trade-off
     skipparts:
       skippa: false
       skipaa: false
       skipca: false
       skippace: false

3. Limit CORS to specific origins

   trustedorigins:
     - http://192.168.1.50:8080 # Specific IPs only

4. Use HTTPS for URL output

   - name: URL
     config:
       url: https://secure-api.example.com # Use HTTPS

Performance

1. Disable unused features

   • Turn off NFC if only scanning MRZ
   • Disable photo reading if not needed
   • Use smart age mode for age verification

2. Optimize logging

   system:
     loglevel: 3 # Warning level for production
     debug: false
     tofile: false

3. Adjust image quality

   nfc:
     images:
       quality: 75 # Lower for faster processing

Reliability

1. Enable logging for troubleshooting

   system:
     tofile: true
     loglevel: 2 # Info level

2. Keep backups of configuration

   • Save your working config.yml
   • Document custom settings

3. Test changes incrementally

   • Modify one section at a time
   • Verify functionality after each change

Getting Help

If you encounter issues with configuration:

1. Check the log files (if tofile: true)
2. Enable debug mode (debug: true, loglevel: 0)
3. Verify YAML syntax - Indentation matters in YAML files!
4. Review examples in this guide
5. Contact support with your configuration file and log files

Quick Reference

Common Settings to Change

File Locations

• Configuration file: config.yml (same folder as application)
• Web interface: ./www/ folder
• Log files: ./logs/ folder (if enabled)
• Output files: Configured in output.outputitems[].config.file_path
• NFC raw files: ./rawnfcfiles/ (if enabled)