Configuration

This section describes the current AT3 configuration parameters. It relies on the configuration service, which supports different types of parameters (integer, float, ASCII string and byte array).

Note: The configuration service does not support parameter names (parameters only have a numeric identifier) or value ranges. In AT3 it is the application which provides parameter names as well as acceptable ranges for each parameter identifier. If the user tries to set parameter that is out of range, its value is not written.

Parameter identifiers and groups

The configuration parameters are grouped per functionality domain. This eases management, particularly when a configuration change affects a single group: Registered software components against the configuration change can decide if the modified parameter group affects them or not.

The parameter identifiers are unique across the entire configuration. These unique identifiers, called full-identifiers, are built from the group identifier and the local identifier. The local identifier is unique only inside a group. The full-identifier is a 16 bits value built with the most significant byte being the group identifier and the local-identifier as the least significant byte.

Full identifier
Bits[15..8]	Bits[7.0]
Group identifier	Local identifier

Note that in the rest of the document the acronym LID refers to the Local Identifier within a group and FID refers to the Full identifier.

There are 4 types of parameters:

• 32-bit signed integer
• 32-bit floating-point number
• String, Null-terminated, ASCII encoded, Max 32 chars including Null
• Byte array, Max 32 Bytes

Currently, the following groups and parameters are defined. Note that the parameter identifiers and names can be subject to change before the first release.

Internal group

This group is specific because it contains the internal system variables that need to be preserved across power down and reset. The system reads from and writes to these variables.

Group 0. Internal
FID	LID	Name	Min	Max	Dflt	U	Comments
0x0000	0	sys_highest_temperature	-100	100	0	0C	Highest temperature reached
0x0001	1	sys_lowest_temperature	-100	100	0	0C	Lowest temperature reached
0x0002	2	sys_power_consumption	0	-	0	mAH	Total power consumed

The CLI has an erase command, which can take the optional keyword all. When this keyword is omitted, the internal group (which stores extreme temperatures, battery levels, etc.) is backup'ed before erasing the flash, then restored. When the keyword all is provided, the internal group is not backup'ed and restarts with the factory default values.

The CLI has a config erase command, which has the following behavior:

• Config erase: It restores the configuration of the tracker to factory default (except internal group)
• Config erase all: It restores the configuration of the tracker to factory default (including internal group)

System core group

The core group contains the configuration parameters of the system.

Group 1. System core
FID	LID	Name	Min	Max	Dflt	U	Comments
0x0100	0	core_monitoring_period	15	-	300	s	Device monitoring period.
0x0101	1	core_status_period	0	-	0	s	Status reporting period.
0x0102	2	core_notif_enable	{0...}	{ff...}	See note	-	Notification enable bit map  class 1 - 4
0x0103	3	core_temp_high_threshold	-100	100	100	0C	Highest temperature detection threshold
0x0104	4	core_temp_low_threshold	-100	100	-100	0C	Lowest temperature detection threshold
0x0105	5	core_temp_hysteresis	-100	100	5	0C	Temperature hysteresis.
0x0106	6	core_button1_map	0	max	0	-	Button 1 mapping
0x0107	7	core_button2_map	0	max	0	-	Button 2 mapping
0x0108	8	core_buttons_timing	See note	max			Button timers (press, long press, debounce)
0x0109	9	core_led0_map	-	-	0	-	LED 0 mapping
0x010A	10	core_led1_map	-	-	0	-	LED 1 mapping
0x010B	11	core_buzzer_map	-	-	See note	-	Buzzer mapping
0x010C	12	core_almanac_validity	7	365	120	days	Number of days for which the GNSS almanac is considered as valid.
0x010D	13	core_almanac_outdated_ratio	0	100	100	%	Percentage of outdated GNSS almanac entries which will trigger network update requests. A value of 100% disables the network requests. Applicable for both LR11xx and MT33xx GNSS devices

core_monitoring_period: Period at which the device manager measures and manages the system variables such as the temperature, the battery level and so on. Refer to section device and power management for more details.

core_status_period: Period at which the status notification is sent. This notification plays the role of the LoRa live uplink in AT2. See also section notifications on notification uplinks.

core_notif_enable: This byte-array configures the uplink notification classes and types to be sent via the network. The index of the array represents the class while the value is a bitmap indicating the notification types inside the class to be sent. The value is so coded as the sum of 2^x^, where x are the types. Example, Notifications to be sent:

• tamper: Class 0, type 3. Value: 2^3^ = 8.
• SOS: class 1, type 0 and 1 (SOS on, SOS off). Value: 2^0^ + 2^1^ = 3
• Temperature high: class 2, type 0. Value: 2^0^ = 1

The byte-array will be set to

{08,03,02,00,00,00}

Default/ Enable Status, Low battery and tamper:

{0B,00,00,00,00,00}

Refer to the section notifications for classes and types.

core_button1_map and core_button2_map: Define the events generated by the button action.

Each event type is coded on 4 bits.

Map:

• Bit 0-3: Event generated on a button press.
• Bit 4-7: Event generated on a button long press.
• Bit 8-11: Event generated on a button single click.
• Bit 12-15: Event generated on a button double click.
• Bit 16-19: Event generated on a button triple click or above.
• Bit 20-23: Event generated on a button simple sequence
• Bit 24-31: RFU

Type of events:

• 0 -- No action
• 1 -- Display battery level on the LED
• 2 -- Start/Stop the SOS
• 3 -- Request a position on demand (POD)
• 4 -- Force an uplink system status notification transmission
• 5 -- Start device
• 6 -- Stop device
• 7 -- Start only SOS
• 8 -- Start BLE advertising for connectivity
• 9..15 - RFU

core_buttons_timing: Define the buttons timing parameters.

Each part of the bitmap is coded as below.

Map:

• Bit 0-3: Duration of the button press in seconds.
• Bit 4-7: Duration of the button long press in seconds.
• Bit 8-15: Debounce duration on button 1 in milliseconds.
• Bit 16-23: Debounce duration on button 2 in milliseconds.
• Bit 24-31: RFU

Notes

• The button press and long press timer values are the same for the two buttons.
• If the event start device is not mapped on either core_button1_map or core_button2_map, the device automatically starts after the startup procedure (skip the off mode)
• If the event stop device is not mapped on either core_button1_map or core_button2_map, the device cannot move to the off state.
• core_buttons_timing : the min value for these parameters is set to 0x000A0A21 and the default value is 0x001E1E63.
  • [Button press: min duration is 1 seconds, default duration is 3 seconds]
  • [Button long press: min duration is 2 seconds, default duration is 6s]
  • [Button debounce on button 1 and 2: min duration is 10ms, default duration is 30ms]
• The duration of the button press cannot be equal or greater than long press.
• The button simple sequence is a hard coded sequence that could be used without starting the special button sequence (with a 14 second press), the simple sequence is as below:
  • Button press for button press duration (by default 3s)
  • Button release for button press duration (by default 3s)
  • Button press for button press duration (by default 3s)

core_led0_map and core_led1_map: Define the LED patterns to be displayed upon given events.

The byte array is split in 10 slices of 3 bytes each. Each slice configures a pattern for a system event.

The parameter is defined as:

Slice 1			Slice 2			...	Slice 10
Byte 0	Byte 1	Byte 2	Byte 0	Byte 1	Byte 2		Byte 0	Byte 1	Byte 2
ext/cls	type	pattern	ext/cls	type	pattern		ext/cls	type	pattern

Where

• ext/cls: Pattern extension and system event class.
  • bit 0..4: System event class. Refer to the Event manager section.
  • bit 5..6: Pattern loop extension (Most significant bits).
  • bit 7: Pattern inversion:
    • 0 -- The pattern is played as defined.
    • 1 -- The pattern is inverted.
• type: System event type. Refer to the Event manager section.
• pattern: Pattern configuration:
  • bit 0..3. Pattern identifier:
    • 0 -- None. Not configured
    • 1 -- LED off. Pattern duration: Infinite
    • 2 -- LED on. Pattern duration: 1s.
    • 3 -- Fade in. Pattern duration: 2.5s. Usually used for device power on.
    • 4 -- Fade out. Pattern duration: 2.5s. Usually used for device power off.
    • 5 -- Blink slow: On: 1000ms, Off: 1000ms. Pattern duration: 2s.
    • 6 -- Blink medium: On: 500ms, Off: 500ms. Pattern duration: 1s.
    • 7 -- Blink fast: On: 250 ms. Off: 250 ms. Pattern duration: 0.5s
    • 8 -- Flash slow: On: 100ms, Off: 2s. Pattern duration: 2.1s.
    • 9 -- Flash fast: On: 100ms, Off: 1s. Pattern duration: 1.1s. Usually used for SOS
    • 10 -- Heart: On: 100ms, Off: 250s, On: 100ms, Off: 1s. Pattern duration: 1.35s.
  • bit 4..7. Pattern loop (Least significant bits): Number of times the pattern is displayed. Used in combination with the Pattern loop extension. A combined value of 0 means infinite.

For more details, refer to the section LED.

core_buzzer_map: Define the buzzer melodies to be played upon given events.

The byte array is split in 10 slices of 3 bytes each. Each slice configures a melody for a system event.

The parameter is defined as:

Slice 1			Slice 2			...	Slice 10
Byte 0	Byte 1	Byte 2	Byte 0	Byte 1	Byte 2		Byte 0	Byte 1	Byte 2
ext/cls	type	melody	ext/cls	type	melody		ext/cls	type	melody

Where

• ext/cls: Melody extension and system event class.

  • bit 0..4: System event class. Refer to the Event manager section.
  • bit 5..7: Melody count extension (Most significant bits).

• type: System event type. Refer to the Event manager section.

• melody: Melody configuration:

  • bit 0..4. Melody identifier:
    • 0 -- None. No configured
    • 1 -- Melody 1: Off. Melody duration: Infinite
    • 2 -- Melody 2
    • 3 -- Melody 3
    • 4 -- Melody 4
  • Bit 5..7. (Least significant bits): Number of times the pattern is displayed. Used in combination with the Pattern count extension. A combined value of 0 means infinite.

Default value:

{09,03,24,09,01,25,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00,00}

Buzzer plays melody 4 when tracker is running an plays the melody 5 when moving to OFF mode.

Geolocation engine group

This group configures the geolocation engine local processing.

Group 2. GEOLOC
FID	LID	Name	Min	Max	Dflt	U	Comments
0x0200	0	geoloc_motion_period	10	86400	600	s	Position acquisition period while in motion
0x0201	1	geoloc_static_period	10	86400	600	s	Position acquisition period while static
0x0202	2	geoloc_sos_period	10	86400	600	s	Position acquisition period while in sos
0x0203	3	geoloc_nb_start	0	10	1	-	Number of acquisitions on motion start event
0x0204	4	geoloc_nb_stop	0	10	1	-	Number of acquisitions on motion stop event
0x0205	5	geoloc_start_stop_period	10	86400	600	s	Interval between position acquisitions while acquiring consecutive positions on motion start or stop
0x0206	6	geoloc_gnss_hold_on_mode	0	4	0	-	Select the GNSS hold on mode. Value:  0: Disabled  1: Always. Hold-on mode always set. Only controlled by the timer.  2: techno: If the gnss is actually used (meaning GNSS techno not skipped).  3: moving: Hold-mode set while moving.  4: techno and moving. if the gnss is actually used (meaning GNSS techno not skipped) and tracker is moving. In modes 2 and 4, the GNSS is immediately stopped if another location technology (e.g. BLE) has been successful and the GNSS technology is configured to be skipped.
0x0207	7	geoloc_gnss_hold_on_timeout	0	86400	0	s	GNSS hold on mode timeout, applicable to all hold-on modes except Disabled. 0 disables the Hold-on mode.
0x0208	8	geoloc_profile0_triggers	0	0xFFFFFFFF	1	-	Geolocation event triggers 0
0x0209	9	geoloc_profile1_triggers	0	0xFFFFFFFF	1	-	Geolocation event triggers 1
0x020A	10	geoloc_profile2_triggers	0	0xFFFFFFFF	1	-	Geolocation event triggers 2
0x020B	11	geoloc_gbe_profile0_techno	-	-		-	Technologies to schedule using the basic engine for events in triggers 0
0x020C	12	geoloc_gbe_profile1_techno	-	-	-	-	Technologies to schedule using the basic engine for events in triggers 1
0x020D	13	geoloc_gbe_profile2_techno	-	-	-	-	Technologies to schedule using the basic engine for events in triggers 2

• geoloc_profileX_triggers : the set bits select the events that will be handled according to profile0 (i.e. the sequence of technologies defined in geoloc_gbe_profileX_techno):
  • bit 0: geo_trigger_pod: Geoloc triggered on Position-on-demand via downlink or via button.
  • bit 1: geo_trigger_sos: SOS started
  • bit 2: geo_trigger_motion_start: Geoloc triggered on motion start event
    • Require the configuration of geoloc_motion_nb_start and geo_start_stop_period
  • bit 3: geo_trigger_motion_stop: Geoloc triggered on motion stop event
    • Require the configuration of geoloc_motion_nb_stop and geo_start_stop_period
  • bit 4: geo_trigger_in_motion: Periodic geoloc while the tracker is in motion
    • Require the configuration of geo_motion_period.
  • bit 5: geo_trigger_in_static: Periodic geoloc running while the tracker is static
    • Require the configuration of geo_static_period.
  • bit 6: geo_trigger_shock: Geoloc triggered on shock action
    • Require the shock detection configured (accelerometer)
  • bit 7: geo_trigger_temp_high_threshold: Geoloc triggered on temperature high.
  • bit 8: geo_trigger_temp_low_threshold: Geoloc triggered on temperature low.
  • bit 9: geo_trigger_geozoning: Geoloc stopped while in monitored area. Enabled when leaving the monitored area.

gbe_profileX_techno

Each byte represents a technology to schedule, coded as follow:

• Bit 7: Action Identifier
• Bits [6..0]: Technology Identifier, encoded as a 6-bit unsigned integer.

Available actions are:

Identifier	Action
0	Skip on success
1	always_done

• Always_Done : the technology must be always scheduled regardless of the success or failure of previous technologies.
• Skip on success: The technology should be scheduled only if all previous technologies failed to acquire a position, i.e. it will be skipped if any of them succeded.

Available technologies are:

Identifier	Technology
0	None
1	LR11xx_A_GNSS
2	WIFI
3	BLE scan 1
4	BLE scan 2
5	aided_GNSS
6	GNSS

See also section Geolocation manager for details on the geolocation manager and configuration examples.

GNSS group

This group configures the MT3333 GNSS.

Group 3. gnss
FID	LID	Name	Min	Max	Dflt	U	Comments
0x0300	0	gnss_constellation	0	6	4	-	GNSS constellations to be used. Supported values: 0. GPS only 1. GLONASS only 2 . GPS and GLONASS 3. GPS and GALILEO 4. GPS, GLONASS and GALILEO 5. BEIDOU only 6. BEIDOU and GPS,
0x0301	1	gnss_max_time	30	300	300	s	GNSS max acquisition time.
0x0302	2	gnss_t0_timeout_static	0	300	30	s	Max time to acquire at least one satellite when the tracker is static
0x0303	3	gnss_ehpe_static	0	100	30	m	Expected Estimated horizontal position error.  used when the tracker is static.
0x0304	4	gnss_convergence_static	0	300	20	s	Extra-time after a first fix to refine the fix. Used when the tracker is static
0x0305	5	gnss_t0_timeout_motion	0	300	30	s	Max time to acquire at least one satellite when the tracker is in motion.
0x0306	6	gnss_ehpe_motion	0	100	30	m	Expected Estimated horizontal position error.  used when the tracker is in motion.
0x0307	7	gnss_convergence_motion	0	300	20	s	Extra-time after a first fix to refine the fix. Used when the tracker is in motion.
0x0308	8	gnss_standby	0	-	14400	s	Max time to let the device in standby mode.
0x0309	9	gnss_agnss_max_time	15	240	45	s	Aided GNSS max acquisition time.
0x030A	10	gnss_t1_timeout	0	300	0	s	Extra time let in Aided GNSS mode to try doing a fix.

LR11xx group

This group configures the LR1110 GNSS.

Group 4. LR1110
FID	LID	Name	Min	Max	Dflt	U	Comments
0x0400	0	lr_constellation	1	6	6	-	GNSS constellations to be used.
0x0401	1	lr_scan_mode	1	2	1	-	(NAV1 / NAV2)
0x0402	2	lr_nb_scans	1	4	2	-	Number of scans for one position acquisition
0x0403	3	lr_inter_scan_time	0	15	5	s	Time to wait between the scans for a position
0x0404	4	lr_max_wifi_bssid	1	32	4	-	Max number of WIFI BSSID per scan

lr_constellation values

• 0. GPS only
• 5. BEIDOU only
• 6. BEIDOU and GPS

lr_scan_mode values

The LR11xx GNSS firmware implements several variants called "NAV<X>", not all maybe available depending on the loaded firmware:

• 1. NAV1 scan
• 2. NAV2 scan

BLE scan group

There are 2 groups to configures two different BLE scans. Each scan has its own parameter set. Filters are available which are defined as masks references to the beginning of the Advertising payload (ADV). Refer to section payload manager for details, including offset zero reference for each type of beacon.

Group 5. BLE_SCAN1 Group 6. BLE SCAN2
FID	LID	Name	Min	Max	Dflt	U	Comments
0x0500 0x0600	0	ble_scan_duration	50	61440	3000	ms	Total time for a BLE scan
0x0501 0x0601	1	ble_scan_window	3	10240	120	ms	Scan window
0x0502 0x0602	2	ble_scan_interval	1	10240	130	ms	Scan interval
0x0503 0x0603	3	ble_scan_type	0	7	0	-	Type of beacons to scan
0x0504 0x0604	4	ble_scan_min_rssi	-120	0	-100	dB	Min RSSI to consider the beacon
0x0505 0x0605	5	ble_scan_filter1_mask	-	-	0	-	Mask (10 bytes) to be applied to the ADV frame.
0x0506 0x0606	6	ble_scan_filter1_value	-	-	0	-	Comparison value (10 bytes) belonging to filter1
0x0507 0x0607	7	ble_scan_filter1_offset	0	21	0	-	Offset in the ADV from which we apply the filter1
0x0508 0x0608	8	ble_scan_filter2_mask	-	-	0	-	Mask (10 bytes) to be applied to the ADV frame.
0x0509 0x0609	9	ble_scan_filter2_value	-	-	0]	-	Comparison value (10 bytes) belonging to filter2
0x050A 0x060A	10	ble_scan_filter2_offset	0	21	0	-	Offset in the ADV from which we apply the filter2
0x050B 0x060B	11	ble_scan_nb_beacons	1	20	4	-	Number of beacons to report
0x050C 0x060C	12	ble_scan_report_type	0	2	0	-	Scan report type
0x050D 0x060D	13	ble_scan_report_id_ofs	0	25	4	-	Offset in ADV to extract the beacon identifier

Note

ADV means BLE advertisement frame

ble_scan_type values

• 0. All beacons.
• 1. Eddystone UUID beacons only.
• 2. Eddystone URL beacons only.
• 3. All Eddystone beacons.
• 4. iBeacon beacons only
• 5. AltBeacon beacons only
• 6. Custom (only based on filters)
• 7. Exposure advertisement

ble_scan_report_type values

• 0. MAC address
• 1. Beacon identifier in short format (2 bytes)
• 2. Beacon identifier in long format (16 bytes).

Refer to the Geolocation manager for the configuration.

Accelerometer group

This group configures the accelerometer.

Group 7. Accelerometer
FID	LID	Name	Min	Max	Dflt	U	Comments
0x0700	0	accelero_motion_sensi	1	48	16	mg	Motion sensitivity. Step 63 mg.
0x0701	1	accelero_motion_duration	10	3600	20	s	Motion duration
0x0702	2	accelero_full_scale	0	3	1	-	Scale use (2,4,8,16 g).
0x0703	3	accelero_output_data_rate	0	4	0	-	Output data rate (12.5, 25, 50, 100, 200 Hz)
0x0704	4	accelero_shock_threshold	0	128	0	mg	Shock threshold. Increments of 63 mg

accelero_full_scale

Acceptable values:

• 0. Scale 2g
• 1. Scale 4g
• 2. Scale 8g
• 3. Scale 16g

accelero_output_data_rate

Acceptable values:

• 0. 12.5 Hz
• 1. 25 Hz
• 2. 50 Hz
• 3. 100 Hz
• 4. 200 Hz

There is currently no filtering on GADD index level, but only on shock level. The back-end application needs to filter based on GADD index value.

Network group

This group configures the general networking.

Group 8. Network
FID	LID	Name	Min	Max	Dflt	U	Comments
0x0800	0	net_selection	0	4	0	-	Define the networking type: ·       0: LoRaWAN only ·       1: Cellular only ·       2: LoRaWAN fallback cellular ·       3: Cellular fallback LoRaWAN
0x0801	1	net_reconnection_spacing	0	Max int	600	s	Interval between connection retries on the primary network, when operating on the fallback network.
0x0802	2	net_main_probe_timeout	120	Max int	600	s	Maximum duration of an attempt to reconnect to the main network

Refer to section Networking for more details on the AT3 network manager.

LoRaWAN group

This group configures the LoRaWAN networking.

Only LoRaWAN OTA mode is supported in AT3. A join is triggered upon initial boot if LoRaWAN is the primary network, or every time LoRaWAN is activated as secondary network. It is also triggered after detection of network loss after failure of lorawan_probe_max_attempts number of link-checks, which are sent only if no downlink message has been received for lorawan_probe_period. All Joins are randomized (the randomization is managed by the LBM stack).

Group 9. LoRaWAN
FID	LID	Name	Min	Max	Dflt	U	Comments
0x0900	0	lorawan_cnx_timeout	0	Max int	0	-	Use only on dual network configurations. Max time to wait for joining the network including all retries (timeout triggers a switch to the back-up network). Value 0 disables the timer (use this value for LoRaWAN only configurations)..
0x0901	1	lorawan_dl_trigger_period	0	Max int	3600	s	Period at which an empty uplink is sent to trigger a Rx window for downlinks (if no uplink has been sent within this period). 0 disables the function.
0x0902	2	lorawan_probe_max_attempts	0	10	0	-	Number of link-check sent before declaring the network as lost
0x0903	3	lorawan_probe_period	120	Max int	600	s	Time between link-check requests, or since last downlink activity.
0x0904	4	lorawan_confirm_notif_map	{0}	{FF}	{0}	-	Map enabling the LoRaWAN confirmed message for notifications.
0x0905	5	lorawan_confirm_notif_retry	0	15	0	-	Number of retries for confirmed messages. Value 0: the number of TX follow ADR.
0x0906	6	lorawan_s1_tx_strategy	1	-	0x109	-	Socket 1. Transmission strategy
0x0907	7	lorawan_s1_ul_port	1	252	19	-	Socket 1. Uplink port
0x0908	8	lorawan_s1_dl_port	1	252	3	-	Socket 1. Downlink port

TX strategy

The parameter lorawan_s1_tx_strategy is a bit-field on 3 bytes providing the LoRa transmission strategy.

The bitfield is defined as follows:

Byte #2 Datarates for the second TX	Byte #1 Datarates for the first TX	Byte #0 Control
x x x x x x x x	x x x x x x x x	0 0 0 0 D M S A

Byte #0 -- Control

• Bit #0 (A). Set to enable LoRaWAN network ADR control when the tracker is static. Reset to disable the network ADR control regardless the motion state of the tracker.
• Bit #1 (S). Control the dual transmission when the tracker is static. Set to enable the dual transmission in static state. Reset to disable it.
• Bit #2 (M). Control the dual transmission when the tracker is in motion. Set to enable the dual transmission in motion state. Reset to disable it in motion state.
• Bit #3 (D). Control the DR (Datarate) modification for over-sized messages. Set to allow AOS to increase the DR for messages not fitting the allowed maximum LoRaWAN payload size for a given datarate. Reset this flag to prevent sending of over-sized messages.
• Bit #4-7: Unused.

Byte #1 -- Datarates enabled for the first transmission.

• Bit #0. Enable datarate DR0. When set, the datarate is enabled.
• Bit #1. Enable datarate DR1. When set, the datarate is enabled.
• ...
• Bit #7. Enable datarate DR7. When set, the datarate is enabled.

Byte #2 -- Datarates enabled for the second transmission.

• Bit #0. Enable datarate DR0. When set, the datarate is enabled.
• Bit #1. Enable datarate DR1. When set, the datarate is enabled.
• ...
• Bit #7. Enable datarate DR7. When set, the datarate is enabled.

Confirm_notif_map.

This byte-array configures the notification classes and uplink types to be sent as LoRaWAN confirmed uplinks. The index of the array represents the class while the value is a bitmap indicating the notification types inside the class to be acknowledged. The value is so coded as the sum of 2^x^, where x are the types. Example, Notifications to be acknowledged:

• tamper: Class 0, type 3. Value: 2^3^ = 8.

• SOS:class 1, type 0 and 1 (SOS on, SOS off). Value: 2^0^ + 2^1^ = 3

• Temperature high: class 2, type 0. Value: 2^0^ = 1

The byte-array will be set to

{08,03,02,00,00,00}

Default value

{00,00,00,00,00,00}

Cellular group

This group configures the cellular network.

Group 10. Cellular
FID	LID	Name	Min	Max	Dflt	U	Comments
0x0A00	0	cell_sim_interface	0	3	0	-	SIM interface 0: SIM0 (0), 1: e-SIM, 2: reserved for future use. 3: reserved for future use.
0x0A01	1	cell_network_type	1	2	1	-	Network type. ·      0: Cellular not used ·       1: LTE-M ·       2: NB-IOT
0x0A02	2	cell_search_bands	0	See note	See note		Radio frequency bands scanned to search a cell. See note.
0x0A03	2	cell_cnx_timeout_static	186	900	300	s	Maximum search duration for a cellular network. Applicable when the tracker is static.
0x0A04	3	cell_cnx_timeout_motion	186	900	300	s	Maximum search duration for a cellular network. Applicable when the tracker is in motion.
0x0A05	4	cell_cnx_nw_lost_timeout	0	900	30	S	Interval betseen reconnection attempts. There are no retries for an administrative disconnect reason, otherwise there are up to cell_cnx_max_attempts retres After this the network manager will attempt to use the fallback technology if any, and try to reconnect to the primary technology with interval net_reconnection_spacing, which is expected to be larger than . cell_cnx_nw_lost_timeout.
0x0A06	5	cell_cnx_max_attempts	1	10	3	-	Maximum number of times the network search may be repeated before shutting down the modem and passing control to the network manager.
0x0A07	6	cell_access_point_name	-	-	“”	-	String (max 32 bytes) providing the service access point name (APN).. If not provided, this information is retrieved from the SIM.
0x0A08	7	cell_operator_sim_slot_0	-	-	“”	-	Cellular operator name when using SIM0
0x0A09	8	cell_operator_sim_slot_1	-	-	“”	-	Cellular operator name when using SIM1 (E.SIM).
0x0A0A	9	cell_low_power_mode	0	3	0	-	Low power mode: ·       0: disabled. ·       1: PSM ·       2: eDRX ·       3. both PSM and eDRX.
0x0A0B	10	cell_psm_tau_period	0	255	254	-	Bit-field giving the requested TAU period.
0x0A0C	11	cell_psm_active_time	0	255	33	-	Bit-field giving the requested active time.
0x0A0D	12	cell_edrx_pcl	0	15		-	Requested paging cycle length
0x0A0E	13	cell_edrx_ptw	0	15	0	-	Requested paging time window
0x0A0F	14	cell_rai_timeout	0	10000	500	ms	RAI (Release Assistance Indication) timeout . A null value disables the feature. Use only with UDP protocol.
0x0A10	15	cell_s1_transport_proto	0	1	1	-	Socket  1 transport protocol : ·       0: TCP ·       1: UDP
0x0A11	16	cell_s1_ip_url_addr	-	-	“”	-	Socket 1 remote IP address or FQDN in string format (max 32 bytes)
0x0A12	17	cell_s1_dst_ip_port	0	65535	0	-	Socket 1 destination UDP/TCP port number.
0x0A13	18	cell_s1_src_ip_port	0	65535	0	-	Socket 1 local UDP/TCP port number. Value 0 means that the modem will choose one.
0x0A14	19	cell_s1_tx_aggr_time	0	3600	120	s	Duration in second for which the messages are buffered in the socket 1 transmit queue before being transmitted

Search bands

This byte array parameter contains the list of cellular bands (encoded in hexadecimal form, e.g. band 28 is coded as 0x18) to scan to find an appropriate cell.

Notes

• Filling this array to 0 instructs the modem to scan all possible bands.
• The array must end by a null value
• Default value:
  • {01,03,08,13,14,1C,00,00,00,00,00,00,00,00,00,00,00,00,00}
• Supported bands
  • {01,02,03,04,05,08,0C,0D,0E,11,12,13,15,19,1A,1C,42,47,55}

Active time bit-field

Bits 4 to 0 represent the binary coded timer value and bits 5 to 7 the timer value unit .

Bits			Timer value unit
B7	B6	B5
0	0	0	Value is incremented in multiples of 2 seconds
0	0	1	Value is incremented in multiples of 1 minute
0	1	0	Value is incremented in multiples of deci-hours
1	1	1	Value indicates that the timer is deactivated.

TAU Time bit-field

Bits 4 to 0 represent the binary coded timer value and bits 5 to 7 the timer value unit.

Bits			Timer value unit
B7	B6	B5
0	0	0	Value is incremented in multiples of 10 minutes
0	0	1	Value is incremented in multiples of 1 hour
0	1	0	Value is incremented in multiples of 10 hours
0	1	1	Value is incremented in multiples of 2 seconds
1	0	0	Value is incremented in multiples of 30 seconds
1	0	1	Value is incremented in multiples of 1 minutes
1	1	0	Value is incremented in multiples of 320 hours
1	1	1	Value indicates that the timer is deactivated

BLE group

This group configures the BLE parameters.

Group 11.  BLE
FID	LID	Name	Min	Max	Dflt	U	Comments
0x0B00	0	ble_cnx_tx_power	0	31	19	-	BLE Tx power level, see table below.
0x0B01	1	ble_cnx_adv_duration	30	Max int	60	s	Time to wait before stopping advertising or switching to slow advertising.
0x0B02	2	ble_cnx_behavior	0	4	1	-	The connectivity configuration.
0x0B03	0	ble_beacon_tx_power	0	31	19	dBm	BLE Tx power level for beaconing.
0x0B04	1	ble_beacon_type	0	5	0	-	Beacon Type to start.
0x0B05	2	ble_beacon_identifier	-	-	-	-	BLE beaconing ID parameter, array of 16 to 24 bytes depending on beacon type.
0x0B06	3	ble_beacon_fast_adv_interval	20	10240	333	ms	BLE beacon fast advertising interval.
0x0B07	4	ble_beacon_slow_adv_interval	20	10240	1000	ms	BLE beacon slow advertising interval.

cnx tx power level

The user can specify the desired TX power via the ble_cnx_tx_power parameter, representing the TX level as defined by ST microelectronics for the STM32WB55, the correspondence between TX power level and TX power dBm is as follows:

Level	dBm	Level	dBm	Level	dBm	Level	dBm	Level	dBm	Level	dBm
0x00	-40	0x06	-15.25	0x0C	-8.85	0x12	-3.15	0x18	-0.15	0x1E	+5
0x01	-20.85	0x07	-14.1	0x0D	-7.8	0x13	-2.45	0x19	0	0X1F	+6
0x02	-19.75	0x08	-13.15	0x0E	-6.9	0x14	-1.8	0x1A	+1
0x03	-18.85	0x09	-12.05	0x0F	-5.9	0x15	-1.3	0x1B	+2
0x04	-17.6	0x0A	-10.9	0x10	-4.95	0x16	-0.85	0x1C	+3
0x05	-16.5	0x0B	-9.9	0x11	-4	0x17	-0.5	0x1D	+4

cnx adv duration

This parameter defines the duration of the fast advertising timer. When the device initiates connectivity, it starts with fast advertising parameters, with the fast advertising interval set to 500ms.

When the device is connected to a mobile app, the fast advertising timer is stopped, and a new timer (ble_timer) is started for 60 seconds to allow the mobile app to proceed with the bonding procedure. If the ble_timer expires, the device will disconnect and restart fast advertising.

When the fast advertising timer is triggered, depending on the configuration and BLE bond status, there could be two actions:

ble_cnx_init_config	Bond exist	No bond
enable_no_passkey	Switch to slow advertising	Connectivity stopped
enable_passkey
enable_no_passkey_no_slow_adv	Connectivity stopped
enable_passkey_no_slow_adv

Slow advertising interval is set to 2 seconds.

cnx behavior

This parameter is used to define the behavior of the connectivity in terms of passkey usage and the actions to take after the fast advertising timer is triggered.

ble_cnx_init_config	Value	Comment
Disable	0	- BLE connectivity not started when the device is turned ON
enable_no_passkey	1	- BLE connectivity started when the device is turned ON - No passkey needed to establish a secure connection
enable_passkey	2	- BLE connectivity started when the device is turned ON - Passkey needed to establish a secure connection
enable_no_passkey_no_slow_adv	3	- BLE connectivity started when the device is turned ON - No passkey needed to establish a secure connection - Switch to BLE Idle state when the fast advertising timer is triggered (Slow advertising disabled)
enable_passkey_no_slow_adv	4	- BLE connectivity started when the device is turned ON - Passkey needed to establish a secure connection - Switch to BLE Idle state when the fast advertising timer is triggered (Slow advertising disabled)

In case of passkey usage, the pin code will be set to the Unique device number value modulo [1000000, this will gives a pin code value between 000000 and 999999.]

Beacon tx power level

Beaconing Tx power level, same as cnx tx power level.

Beacon type

Beacon type	Value	Comment
Disabled	0	Beaconing disabled
Eddystone UID	1	Eddystone UUID beacon emulation
I-Beacon	2	I-Beacon beacon emulation
AltBeacon	3	AltBeacon beacon emulation
QUUPPA	4	QUUPPA beacon emulation
Exposure	5	Exposure beacon emulation

Beacon identifier

This parameter will host the data to advertise in beaconing mode, the max size of this parameter is 24 bytes and minimum size is 16 bytes.

The data to advertise and the data size depends on the beacon type:

• Eddystone UID: 10 bytes of namespace followed by 6 bytes of instance.
• Ibeacon: 16 bytes for company UUID followed by 2 bytes for major number and 2 bytes for minor number.
• Altbeacon: 4 bytes for manufacturer ID followed by 20 bytes for beacon ID.
• QUUPPA: 1 byte for compensated Tx power followed by 6 bytes for identifier.
• Exposure: 16 bytes for random public identifier followed by 4 bytes for meta data.

By default the data is set to 0.

Beacon fast advertising interval

The fast advertising interval is used when the device is in motion state.

Beacon slow advertising interval

The slow advertising interval is used when the device is in static state.

Configuration file

Overview

AT3 supports a configuration file appended to the firmware binary. The configuration file contains:

• A header including the keyword CONFIGURATION followed by the VERSION keyword and its version number.
• The list of the parameters that differs from the hard-coded ones.
• A trailer indicating the end of the configuration

Each parameter is addressed by its full identifier coded in hexadecimal and prefixed with the letter P. The full identifier must contains all 4 digits.

Examples

• P0102 is a valid identifier (parameter group 1, local identifier 2), while P102, P12 are not a valid. .

P0000 is a valid identifier (parameter group 0, local identifier 0), while any other writing for this parameter identifier is invalid.

Important notes

• All keywords as well as the parameter identifier prefix must be in upper case.
• There can be only one keyword per line.
• There can be only one parameter per line
• Each line is ended by a CR or LF or both.

Version format

The configuration version starts on a single line starting with the keyword VERSION followed by a space and the version number.

The number contains 4 fields separated by a dot.The general format is Major.minor.iteration.user.

Example

VERSION 1.0.0.1

The meaning and the management of the version is described hereafter in section Configuration management.

Parameter format

There is a single parameter setting per line. The line is composed by:

• The parameter full identifier prefixed by the letter P
• The equal sign, separating the identifier from its value
• The desired value of the parameter

Note that spaces may be inserted before and after the equal sign.

AT3 uses several parameter types. They are automatically discovered based on the value syntax:

• An integer value type is detected if it contains only numerical digits [0..9].

Examples: 123, 0141, 1234 are valid integer numbers.

• An hexadecimal value is detected if the value starts with 0x and numerical digits [0..9] or letters [a..f] or [A..F] only follows the 0x prefix.

Examples: 0x12aa, 0x45678, 0xFF123 are valid.

• A decimal number must contain a dot. Ie value 1 must be configured as "1.0."

Examples: 1.23, 11234.0, 12345 are valid.

• An ASCII string must be enclosed by the double quote ("). A string cannot include a double quote and cannot exceed 31 characters. Empty strings are supported.

Examples: "abeeway", "Hello word", "" are valid.

• A byte array must start with the opening bracket ({) and end with the closing bracket (}). Each value is expressed in hexadecimal on 2 digits and separated by a comma (,). No space are allowed between the 2 brackets. The hexadecimal value is not prefixed with 0x.

Examples: {00, 01,aa,ff,BB,1C} is valid.

Configuration file example

In this example, we modify the parameters core_status_period (0x0102), geoloc_motion_period (0x0200), geoloc_static_period (0x0201), geoloc_start_stop_period (0x0205) and geoloc_gbe_profile0_techno (0x020b).

CONFIGURATION

VERSION 1.0.0.1

P0102=900

P0200= 800

P0201 =300

P0205 = 0x125

P020b = {02,85,00,00,00}

END

Configuration management

Overview

The versioning control field of a configuration allows to check its compatibility with the firmware, and also provides indications for the intended use.

The versioning control field is coded as follows:

<Major>.<Minor>.<Iteration>.<User>

<Major>.<Minor> reflect the first (oldest) firmware version compatible with this configuration. Firmware with the same major version and same or higher minor versions will also be compatible with this configuration as Abeeway ensures upward compatibility within a given major version. A change of major version may break such compatibility (for example it may change the type of a parameter).

<Iteration> is intended to capture the serial number of configurations, and it is expected that it will be incremented at each change.

<User> is a free field, but the intended use is to identify a specific use case or context, and allow the people in charge of device management to rapidly check whether a configuration was designed for the specific use case. Abeeway will use <User>=0 for its generic product configurations out of factory.

Firmware upgrade behavior:

• FW1/ If the new firmware major version is the same as the current configuration stored in flash memory, and the minor version of the firmware is the same or higher, the flash configuration is valid and will be used. Configuration defined values will replace the default values of the firmware.

• The flash configuration <Minor> will be updated  to match the one of the new firmware (as the new firmware may update a parameter, we can no longer guarantee the compatibility of the configuration with the previous firmware).

• FW2/ In all other cases, the current flash configuration is erased, and the firmware will use the default new firmware configuration. Implicitly the versioning control field of this default configuration is <FW_Major>.<MW.Minor>.0.0

Configuration update behavior

• The following must be both true:

  • The new configuration <Major> must be identical to the flash configuration >Major> (which itself always matches the running firmware Major due to rule FW2).

  • The new configuration <Minor> must be lower or equal to the flash configuration <Minor>, which itself always matches the running firmware Minor due to rule FW1).

If it is not the case, the configuration is rejected, as a firmware upgrade is required first to ensure compatibility with the configuration.

If both checks pass the configuration is accepted.

• If the configuration command flag is "replace" then the flash configuration is first erased and replaced with the new parameters. Parameters not specified in the new configuration return to their firmware-defined default values.

• If the configuration command flag is "patch" and either <Iteration> or <User> differ from the current configuration, then the configuration is updated with the new parameters,

• The flash <Iteration> and <User> elements are updated to match the new configuration.

Note that in the case of FUOTA FW upgrade which may also include a configuration, the order of execution is the following:

1/ Firmware upgrade and merge of current config with rules FW1 and FW2

2/ Configuration upgrade (and therefore at the time, the running firmware version is the new FUOTA upgraded firmware).

Configuration commands and actions

The configuration in flash can be reset to the default values at any time. This action can be done via the CLI command, the network command or the bootloader:

• The networking integrates a command, which clears and resets the tracker (refer to the downlink commands).
• The Bootloader includes the command ABWe, which erases the flash segment containing the configuration. Once reset, this flash section will be recreated by the application.
• The CLI commands config erase and system reset, respectively erase and reformat the flash and reset the device.