Per-Country or Per-device settings

Per-Country settings can be provided by:

  • UWB_COUNTRY_CODE_CAPS
  • or Extra calibrations files.

If the same parameter was specified by both UWB_COUNTRY_CODE_CAPS and Extra calibration files, UWB_COUNTRY_CODE_CAPS has higher priority. For example, if UWB_COUNTRY_CODE_CAPS has 0x5 (Tx power) entry, cal.antX.chX.tx_power from extra calibration file is ignored.

UWB_COUNTRY_CODE_CAPS

This is for per-country device settings and calibrations.

Multiple UWB_COUNTRY_CODE_CAPS files can define this values. Only one file with highest VERSION will be picked by HAL. And one parameter holds settings for each country code.

Directories contain UWB_COUNTRY_CODE_CAPS are listed by COUNTRY_CODE_CAP_FILE_LOCATION in the main configuration file.

Example:

# /vendor/etc/libuwb-nxp.conf:

COUNTRY_CODE_CAP_FILE_LOCATION={  "/vendor/etc/uwb/", "/data/vendor/uwb/" }

From the above example, /vendor/etc/uwb/libuwb-countrycode.conf and /data/vendor/uwb/libuwb-country.conf will be looked up by HAL and only one file with higher VERSION will be choosen.

  • UWB_COUNTRY_CODE_CAPS
    • First octec has number of TLV entries and TLVs are followed.
    • TLV types:
      • 00 : country code in two letters
      • 01 : 0=Disable UWB, 1=Enable UWB(default)
      • 02 : 0=Disable Channel 5, 1=Enable Channel 5 (default)
      • 03 : 0=Disable Channel 9, 1=Enable Channel 9 (default)
      • 05 : Tx power adjustment values in 2 octects
  • VERSION
    • string formatted number

Example:

# /data/vendor/uwb/libuwb-countrycode.conf:

VERSION="02"
UWB_COUNTRY_CODE_CAPS={
    03,                 #  3 countries
    00, 02, 52, 55,     # 'RU'
    03, 01, 00,         # Disable Channel 9
    05, 02, 81, 05,     # TX_POWER = {81, 05}

    00, 02, 55, 41,     # 'UA'
    01, 01, 00,         # Disable UWB at all

    00, 02, 4b, 52,     # 'KR'
    02, 01, 00,         # Disable Channel 5
    05, 02, 00, 00,     # TX_POWER = {00, 00}
}

Extra calibrations files

Main configuration can specifies additional extra calibrations with EXTRA_CONF_PATH_[1..10] parameters.

  • EXTRA_CONF_PATH[N+1] has higher priority over EXTRA_CONF_PATH[N].
  • if the file path has <country> in it, <country> part will be replaced with country code (or region string)
  • if the file path has <sku> in it, <sku> part will be replace with the ‘persist.vendor.uwb.cal.sku’ property value. if persist.vendor.uwb.cal.sku is unspecified, HAL will try to use defaultsku as a default.
  • if the file path has <revision> in it, <revision> part will be replace with the ‘persist.vendor.uwb.cal.revision’ property value. if persist.vendor.uwb.cal.revision is unspecified, HAL will try to use defaultrevision as a default.

Example:

# /vendor/etc/libuwb-nxp.conf:

EXTRA_CONF_PATH_1="/vendor/etc/uwb/cal-base.conf"
EXTRA_CONF_PATH_2="/vendor/etc/uwb/cal-<sku>.conf"
EXTRA_CONF_PATH_3="/vendor/etc/uwb/cal-<country>.conf"
EXTRA_CONF_PATH_4="/vendor/etc/uwb/cal-<revision>.conf"
EXTRA_CONF_PATH_5="/mnt/vendor/persist/uwb/cal-factory.conf"

Region mapping

To reduce the duplicated settings between countries, multiple country codes can be grouped into region string. If main configuration file has REGION_MAP_PATH, HAL will load region mapping file and use it for region mapping to country codes.

Example:

# /vendor/etc/libuwb-nxp.conf:
REGION_MAP_PATH="/vendor/etc/uwb/regions.conf"

# /vendor/etc/uwb/regions.conf:
FCC="US CA"

In the above example, ‘US’ and ‘CA’ country codes are grouped into ‘FCC’ region string.

When the system provides country code with ‘US’, EXTRA_CONF_PATH_2=/vendor/etc/uwb/cal-<country>.conf* will be evaluated as /vendor/etc/uwb/cal-FCC.conf instead of /vendor/etc/uwb/cal-US.conf and cal-FCC.conf will be loaded.

Parameters

cal.uwb_disable=<1|0>

Per-country, Disable UWB RF when it's set to 1. Default is 0.

cal.rx_antenna_mask=<8bit unsigned>, cal.tx_antenna_mask=<8bit unsigned>

1 octect, Antenna IDs defined by the device. b0=Antenna-ID 1, b1=Antenna-ID 2, ...

e.g. cal.rx_antenna_mask=0x3 means this paltform has two RX antennas with ID 1 and 2.

cal.restricted_channels=<16bit unsigned>

Per country, Restricted channel mask, b0=Channel0, b1=Channel1, ... b15=Channel15. e.g. cal.restricted_channels=0x20 to deactivate channel 5.

cal.otp.xtal=<1|0>

Load the Crystal calibration value from OTP when it's 1. cal.xtal will be ignored.

cal.xtal=<byte array>

6 bytes Crystal calibration values (little endian)

  • [5:4] : CAP1
  • [3:2] : CAP2
  • [1:0] : GM CURRENT CONTROL

e.g. cal.xtal={11 00 11 00 3f 00}

RX antenna delay

  • cal.ant<antenna-id>.ch<channel-number>.ant_delay=<16bit unsigned>

    Default RX antenna delay value in Q14.2.

  • cal.ant<antenna-id>.ch<channel-number>.ant_delay.force_version=<16bit unsigned>

    Forcefully override ...ant_delay value by specifying version number. Platform can specify multiple version numbers for selecting alternate delay values using ...ant_delay.force_value.<version> property.

  • cal.ant<antenna-id>.ch<channel-number>.ant_delay.force_value.<version>=<16bit unsigned>

    Alternate RX antenna delay value in Q14.2. HAL will take this value if ...ant_delay.force_version=<version> and and ant_delay.force_value.<version> are provided.

e.g.

cal.ant1.ch5.ant_delay=2000
cal.ant1.ch5.ant_delay.force_version=2
cal.ant1.cht.ant_delay.force_value.1=2100
cal.ant1.cht.ant_delay.force_value.2=2200

In the above example, HAL applies 2200 for the antenna delay.

cal.ant<antenna-id>.ch<channel-number>.tx_power=<byte array>

Per-country, 4 bytes TX Power value.

  • [3:2] : Delta peak

  • [1:0] : ID RMS

    e.g. cal.ant1.ch5.tx_power={01 00 00 00}

cal.tx_pulse_shape

Per-country, Byte array for TX pulse shape data

cal.ddfs_enable=<1|0>

Per-country, Enable DDFS tone generation. Default is 0.

cal.dc_suppress=<1|0>

Per-country, Enable DC supression. Default is 0.

Example configuration files

# /vendor/etc/libuwb-nxp.conf:
...
REGION_MAP_PATH="/vendor/etc/uwb/regions.conf"

EXTRA_CONF_PATH_1="/vendor/etc/uwb/cal-base.conf"
EXTRA_CONF_PATH_2="/vendor/etc/uwb/cal-<sku>.conf"
EXTRA_CONF_PATH_3="/vendor/etc/uwb/cal-<country>.conf"
EXTRA_CONF_PATH_4="/vendor/etc/uwb/cal-<sku>-<revision>.conf"
EXTRA_CONF_PATH_5="/mnt/vendor/persist/uwb/cal-factory.conf"

# /vendor/etc/uwb/cal-base.conf:
cal.rx_antenna_mask=0x03
cal.tx_antenna_mask=0x01
cal.otp.xtal=1
cal.restricted_channels=0

# /vendor/etc/uwb/cal-defaultsku.conf:
# effective when persist.vendor.uwb.cal.sku is unspecified
cal.ant1.ch5.tx_power={01, 00, 02, 00}
cal.ant1.ch9.tx_power={01, 00, 03, 00}

# /vendor/etc/uwb/cal-modelA.conf:
# effective when persist.vendor.uwb.cal.sku=modelA
cal.ant1.ch5.tx_power={01, 00, 12, 00}
cal.ant1.ch9.tx_power={01, 00, 13, 00}

# /vendor/etc/uwb/cal-FCC.conf:
cal.restricted_channel=0x0

# /vendor/etc/uwb/cal-JP.conf:
cal.restricted_channel=0x20
cal.ddfs_enable=1
cal.ddfs_tone_config={...}

# /vendor/etc/uwb/cal-KR.conf:
cal.restricted_channel=0x20

# /vendor/etc/uwb/cal-TW.conf:
cal.restricted_channel=0x20

# /vendor/etc/uwb/cal-RESTRICTED.conf:
cal.uwb_disable=1
cal.restricted_channels=0xffff

# /vendor/etc/uwb/regions.conf:
CE="AT BE BG CH CY CZ DE DK EE ES FI FR GB GR HR HU IE IS IT LI LV LT LU MT NI NL NO PL PT RO SE SK SI"
FCC="US CA"
RESTRICTED="AR AM AZ BY ID KZ KG NP PK PY RU SB TJ TM UA UZ"

# /vendor/etc/uwb/cal-modelA-EVT.conf:
# effective when persist.vendor.uwb.cal.sku=modelA && persist.vendor.uwb.cal.revision=EVT
cal.ant1.ch5.tx_power={02, 00, 11, 00}
cal.ant1.ch9.tx_power={02, 00, 12, 00}