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
74Example:
75
76```
77# /vendor/etc/libuwb-nxp.conf:
78
79EXTRA_CONF_PATH_1="/vendor/etc/uwb/cal-base.conf"
80EXTRA_CONF_PATH_2="/vendor/etc/uwb/cal-<sku>.conf"
81EXTRA_CONF_PATH_3="/vendor/etc/uwb/cal-<country>.conf"
82EXTRA_CONF_PATH_4="/mnt/vendor/persist/uwb/cal-factory.conf"
83```
84
85#### Region mapping
86
87To 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.
88
89Example:
90
91```
92# /vendor/etc/libuwb-nxp.conf:
93REGION_MAP_PATH="/vendor/etc/uwb/regions.conf"
94
95# /vendor/etc/uwb/regions.conf:
96FCC="US CA"
97```
98
99In the above example, 'US' and 'CA' country codes are grouped into 'FCC' region string.
100
101When 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.
102
103#### Parameters
104
105##### *cal.uwb_disable`=<1|0>`*
106
107Per-country, Disable UWB RF when it's set to 1. Default is 0.
108
109##### *cal.rx_antenna_mask*`=<8bit unsigned>`, *cal.tx_antenna_mask*`=<8bit unsigned>`
110
1111 octect, Antenna IDs defined by the device. b0=Antenna-ID 1, b1=Antenna-ID 2, ...
112
113e.g. `cal.rx_antenna_mask=0x3` means this paltform has two RX antennas with ID 1 and 2.
114
115##### *cal.restricted_channels*`=<16bit unsigned>`
116
117Per country, Restricted channel mask, b0=Channel0, b1=Channel1, ... b15=Channel15.
118e.g. `cal.restricted_channels=0x20` to deactivate channel 5.
119
120##### *cal.otp.xtal*`=<1|0>`
121
122Load the Crystal calibration value from OTP when it's 1. *cal.xtal* will be ignored.
123
124##### *cal.xtal*`=<byte array>`
125
1266 bytes Crystal calibration values (little endian)
127
128- [5:4] : CAP1
129- [3:2] : CAP2
130- [1:0] : GM CURRENT CONTROL
131
132e.g. `cal.xtal={11 00 11 00 3f 00}`
133
134##### *cal.ant`<antenna-id>`.ch`<channel-number>`.ant_delay*`=<16bit unsigned>`
135
136Per-country, RX antenna delay value in Q14.2. e.g. `cal.ant1.ch5.ant_delay=2000`
137
138##### *cal.ant`<antenna-id>`.ch`<channel-number>`.tx_power*`=<byte array>`
139
140Per-country, 4 bytes TX Power value.
141
142- [3:2] : Delta peak
143- [1:0] : ID RMS
144
145  e.g. `cal.ant1.ch5.tx_power={01 00 00 00}`
146
147##### *cal.tx_pulse_shape*
148
149Per-country, Byte array for TX pulse shape data
150
151##### *cal.ddfs_enable`=<1|0>`*
152
153Per-country, Enable DDFS tone generation. Default is 0.
154
155##### *cal.dc_suppress`=<1|0>`*
156
157Per-country, Enable DC supression. Default is 0.
158
159#### Example configuration files
160```
161# /vendor/etc/libuwb-nxp.conf:
162...
163REGION_MAP_PATH="/vendor/etc/uwb/regions.conf"
164
165EXTRA_CONF_PATH_1="/vendor/etc/uwb/cal-base.conf"
166EXTRA_CONF_PATH_2="/vendor/etc/uwb/cal-<sku>.conf"
167EXTRA_CONF_PATH_3="/vendor/etc/uwb/cal-<country>.conf"
168EXTRA_CONF_PATH_4="/mnt/vendor/persist/uwb/cal-factory.conf"
169
170# /vendor/etc/uwb/cal-base.conf:
171cal.rx_antenna_mask=0x03
172cal.tx_antenna_mask=0x01
173cal.otp.xtal=1
174cal.restricted_channels=0
175
176# /vendor/etc/uwb/cal-defaultsku.conf:
177# effective when persist.vendor.uwb.cal.sku is unspecified
178cal.ant1.ch5.tx_power={01, 00, 02, 00}
179cal.ant1.ch9.tx_power={01, 00, 03, 00}
180
181# /vendor/etc/uwb/cal-modelA.conf:
182# effective when persist.vendor.uwb.cal.sku=modelA
183cal.ant1.ch5.tx_power={01, 00, 12, 00}
184cal.ant1.ch9.tx_power={01, 00, 13, 00}
185
186# /vendor/etc/uwb/cal-FCC.conf:
187cal.restricted_channel=0x0
188
189# /vendor/etc/uwb/cal-JP.conf:
190cal.restricted_channel=0x20
191cal.ddfs_enable=1
192cal.ddfs_tone_config={...}
193
194# /vendor/etc/uwb/cal-KR.conf:
195cal.restricted_channel=0x20
196
197# /vendor/etc/uwb/cal-TW.conf:
198cal.restricted_channel=0x20
199
200# /vendor/etc/uwb/cal-RESTRICTED.conf:
201cal.uwb_disable=1
202cal.restricted_channels=0xffff
203
204# /vendor/etc/uwb/regions.conf:
205CE="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"
206FCC="US CA"
207RESTRICTED="AR AM AZ BY ID KZ KG NP PK PY RU SB TJ TM UA UZ"
208```
209