1## Per-Country or Per-device settings
2
3Per-Country settings can be provided by:
4
5- *UWB_COUNTRY_CODE_CAPS*
6- or Extra calibrations files.
7
8If the same parameter was specified by both *UWB_COUNTRY_CODE_CAPS* and
9Extra calibration files, *UWB_COUNTRY_CODE_CAPS* has higher priority.
10For example, if *UWB_COUNTRY_CODE_CAPS* has 0x5 (Tx power) entry, *cal.antX.chX.tx_power* from extra calibration file is ignored.
11
12### UWB_COUNTRY_CODE_CAPS
13
14This is for per-country device settings and calibrations.
15
16Multiple *UWB_COUNTRY_CODE_CAPS* files can define this values.
17Only one file with highest *VERSION* will be picked by HAL. And one parameter holds settings for each country code.
18
19Directories contain *UWB_COUNTRY_CODE_CAPS* are listed by *COUNTRY_CODE_CAP_FILE_LOCATION*
20in the main configuration file.
21
22Example:
23
24``````
25# /vendor/etc/libuwb-nxp.conf:
26
27COUNTRY_CODE_CAP_FILE_LOCATION={  "/vendor/etc/uwb/", "/data/vendor/uwb/" }
28``````
29
30From the above example, `/vendor/etc/uwb/libuwb-countrycode.conf` and
31`/data/vendor/uwb/libuwb-country.conf` will be looked up by HAL and only one file with higher VERSION will be choosen.
32
33* *UWB_COUNTRY_CODE_CAPS*
34  * First octec has number of TLV entries and TLVs are followed.
35  * TLV types:
36     * 00 : country code in two letters
37     * 01 : 0=Disable UWB, 1=Enable UWB(default)
38     * 02 : 0=Disable Channel 5, 1=Enable Channel 5 (default)
39     * 03 : 0=Disable Channel 9, 1=Enable Channel 9 (default)
40     * 05 : Tx power adjustment values in 2 octects
41* *VERSION*
42  * string formatted number
43
44Example:
45
46```
47# /data/vendor/uwb/libuwb-countrycode.conf:
48
49VERSION="02"
50UWB_COUNTRY_CODE_CAPS={
51    03,                 #  3 countries
52    00, 02, 52, 55,     # 'RU'
53    03, 01, 00,         # Disable Channel 9
54    05, 02, 81, 05,     # TX_POWER = {81, 05}
55
56    00, 02, 55, 41,     # 'UA'
57    01, 01, 00,         # Disable UWB at all
58
59    00, 02, 4b, 52,     # 'KR'
60    02, 01, 00,         # Disable Channel 5
61    05, 02, 00, 00,     # TX_POWER = {00, 00}
62}
63```
64
65### Extra calibrations files
66
67Main configuration can specifies additional extra calibrations with *EXTRA_CONF_PATH_[1..10]* parameters.
68
69* *EXTRA_CONF_PATH[N+1]* has higher priority over *EXTRA_CONF_PATH[N]*.
70* if the file path has `<country>` in it, `<country>` part will be replaced with country code (or region string)
71* if the file path has `<sku>` in it, `<sku>` part will be replace with the 'persist.vendor.uwb.cal.sku' property value.
72  if `persist.vendor.uwb.cal.sku` is unspecified, HAL will try to use `defaultsku` as a default.
73* if the file path has `<revision>` in it, `<revision>` part will be replace with the 'persist.vendor.uwb.cal.revision' property value.
74  if `persist.vendor.uwb.cal.revision` is unspecified, HAL will try to use `defaultrevision` as a default.
75
76Example:
77
78```
79# /vendor/etc/libuwb-nxp.conf:
80
81EXTRA_CONF_PATH_1="/vendor/etc/uwb/cal-base.conf"
82EXTRA_CONF_PATH_2="/vendor/etc/uwb/cal-<sku>.conf"
83EXTRA_CONF_PATH_3="/vendor/etc/uwb/cal-<country>.conf"
84EXTRA_CONF_PATH_4="/vendor/etc/uwb/cal-<revision>.conf"
85EXTRA_CONF_PATH_5="/mnt/vendor/persist/uwb/cal-factory.conf"
86```
87
88#### Region mapping
89
90To 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.
91
92Example:
93
94```
95# /vendor/etc/libuwb-nxp.conf:
96REGION_MAP_PATH="/vendor/etc/uwb/regions.conf"
97
98# /vendor/etc/uwb/regions.conf:
99FCC="US CA"
100```
101
102In the above example, 'US' and 'CA' country codes are grouped into 'FCC' region string.
103
104When 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.
105
106#### Parameters
107
108##### *cal.uwb_disable`=<1|0>`*
109
110Per-country, Disable UWB RF when it's set to 1. Default is 0.
111
112##### *cal.rx_antenna_mask*`=<8bit unsigned>`, *cal.tx_antenna_mask*`=<8bit unsigned>`
113
1141 octect, Antenna IDs defined by the device. b0=Antenna-ID 1, b1=Antenna-ID 2, ...
115
116e.g. `cal.rx_antenna_mask=0x3` means this paltform has two RX antennas with ID 1 and 2.
117
118##### *cal.restricted_channels*`=<16bit unsigned>`
119
120Per country, Restricted channel mask, b0=Channel0, b1=Channel1, ... b15=Channel15.
121e.g. `cal.restricted_channels=0x20` to deactivate channel 5.
122
123##### *cal.otp.xtal*`=<1|0>`
124
125Load the Crystal calibration value from OTP when it's 1. *cal.xtal* will be ignored.
126
127##### *cal.xtal*`=<byte array>`
128
1296 bytes Crystal calibration values (little endian)
130
131- [5:4] : CAP1
132- [3:2] : CAP2
133- [1:0] : GM CURRENT CONTROL
134
135e.g. `cal.xtal={11 00 11 00 3f 00}`
136
137##### RX antenna delay
138
139* *cal.ant`<antenna-id>`.ch`<channel-number>`.ant_delay*`=<16bit unsigned>`
140
141  Default RX antenna delay value in Q14.2.
142
143* *cal.ant`<antenna-id>`.ch`<channel-number>`.ant_delay.force_version*`=<16bit unsigned>`
144
145  Forcefully override *...ant_delay* value by specifying version number.
146  Platform can specify multiple version numbers for selecting alternate delay values
147  using *...ant_delay.force_value.`<version>`* property.
148
149* *cal.ant`<antenna-id>`.ch`<channel-number>`.ant_delay.force_value.`<version>`*`=<16bit unsigned>`
150
151  Alternate RX antenna delay value in Q14.2.
152  HAL will take this value if *...ant_delay.force_version=`<version>`* and
153  and *ant_delay.force_value.`<version>`* are provided.
154
155e.g.
156```
157cal.ant1.ch5.ant_delay=2000
158cal.ant1.ch5.ant_delay.force_version=2
159cal.ant1.cht.ant_delay.force_value.1=2100
160cal.ant1.cht.ant_delay.force_value.2=2200
161```
162
163In the above example, HAL applies 2200 for the antenna delay.
164
165##### *cal.ant`<antenna-id>`.ch`<channel-number>`.tx_power*`=<byte array>`
166
167Per-country, 4 bytes TX Power value.
168
169- [3:2] : Delta peak
170- [1:0] : ID RMS
171
172  e.g. `cal.ant1.ch5.tx_power={01 00 00 00}`
173
174##### *cal.tx_pulse_shape*
175
176Per-country, Byte array for TX pulse shape data
177
178##### *cal.ddfs_enable`=<1|0>`*
179
180Per-country, Enable DDFS tone generation. Default is 0.
181
182##### *cal.dc_suppress`=<1|0>`*
183
184Per-country, Enable DC supression. Default is 0.
185
186#### Example configuration files
187```
188# /vendor/etc/libuwb-nxp.conf:
189...
190REGION_MAP_PATH="/vendor/etc/uwb/regions.conf"
191
192EXTRA_CONF_PATH_1="/vendor/etc/uwb/cal-base.conf"
193EXTRA_CONF_PATH_2="/vendor/etc/uwb/cal-<sku>.conf"
194EXTRA_CONF_PATH_3="/vendor/etc/uwb/cal-<country>.conf"
195EXTRA_CONF_PATH_4="/vendor/etc/uwb/cal-<sku>-<revision>.conf"
196EXTRA_CONF_PATH_5="/mnt/vendor/persist/uwb/cal-factory.conf"
197
198# /vendor/etc/uwb/cal-base.conf:
199cal.rx_antenna_mask=0x03
200cal.tx_antenna_mask=0x01
201cal.otp.xtal=1
202cal.restricted_channels=0
203
204# /vendor/etc/uwb/cal-defaultsku.conf:
205# effective when persist.vendor.uwb.cal.sku is unspecified
206cal.ant1.ch5.tx_power={01, 00, 02, 00}
207cal.ant1.ch9.tx_power={01, 00, 03, 00}
208
209# /vendor/etc/uwb/cal-modelA.conf:
210# effective when persist.vendor.uwb.cal.sku=modelA
211cal.ant1.ch5.tx_power={01, 00, 12, 00}
212cal.ant1.ch9.tx_power={01, 00, 13, 00}
213
214# /vendor/etc/uwb/cal-FCC.conf:
215cal.restricted_channel=0x0
216
217# /vendor/etc/uwb/cal-JP.conf:
218cal.restricted_channel=0x20
219cal.ddfs_enable=1
220cal.ddfs_tone_config={...}
221
222# /vendor/etc/uwb/cal-KR.conf:
223cal.restricted_channel=0x20
224
225# /vendor/etc/uwb/cal-TW.conf:
226cal.restricted_channel=0x20
227
228# /vendor/etc/uwb/cal-RESTRICTED.conf:
229cal.uwb_disable=1
230cal.restricted_channels=0xffff
231
232# /vendor/etc/uwb/regions.conf:
233CE="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"
234FCC="US CA"
235RESTRICTED="AR AM AZ BY ID KZ KG NP PK PY RU SB TJ TM UA UZ"
236
237# /vendor/etc/uwb/cal-modelA-EVT.conf:
238# effective when persist.vendor.uwb.cal.sku=modelA && persist.vendor.uwb.cal.revision=EVT
239cal.ant1.ch5.tx_power={02, 00, 11, 00}
240cal.ant1.ch9.tx_power={02, 00, 12, 00}
241```
242