settings_types.h file contains all structures and enums used in settings module, that are used in subsequent files and do not need to be auto-generated at build time.

Enum

conversion_t

enum conversion_t defines all possible data types used in settings:

• UINT8_T = 1,

• UINT16_T = 2,

• UINT32_T = 3,

hw_type

hw_type defines all possible HW versions that are supported.

• wisentedge_nrf52840 = 1

fw_type

fw_type defines all possible FW versions that are supported in FW.

• lion_tracker = 1

Settings

Structures containing settings governing settings, values, messages and commands communication and fields. Mainly containing port number for specific type.

• fw_version

  • major

  • minor

Values

Definitions of structs holding values and settings of certain types:

• value_uint8

• value_uint16

• value_uint32

Each structure is of the same format containing:

• uint8_t id - id of setting or value

• bool enabled - is setting or value enabled

• def_val

Note that float values are stored as int16_t array[2] with encoding:

array[0] = (int16_t) float_val

and

array[1] = (int16_t) (float_val - array[0]) * 10000

Python parser py2h.py and validation script validate_data.py are used to convert settings.json file to c files.

In particular the following files are generated:

• hardware_def.h - containing only definitions from "hardware" field

• settings_def.h and settings_def.c - containing settings structure and auto-generated functions for access and writing to structure

• commands_def.h and commands_def.c - commands defines and settings

• values_def.h and values_def.c - containing main values structure and auto-generated functions for access and writing to structure

• messages_def.h and messages_def.c - message defines and messages

All auto-generated files are equipped with /* AUTOGENERATED FILE - DO NOT MODIFY! */ comment. Sections below describe content of each generated file and helping files.

settings_def.h

Defines

SETTING_TYPE(_id) TYPE_##_id

Returns data type for setting with specified ID.

SETTINGS_STRUCT(_id) STRUCT_##_id

Returns value struct based on setting ID.

Main settings

main_settings struct is auto-generated to contain all settings as defined in settings.json file. In addition to value structs containing settings, it contains:

• n_settings - number of settings

• settings_id - array containing all settings ids

• settings_length - array containing all settings lengths

Global variables

Main_settings is global main_settings struct, accessible in all threads and modules that contains all settings data.

Settings_defines is global settings_defines struct , accessible in all threads and modules that contains settings for receiving and sending settings.

Functions

void *get_setting_struct_by_id(uint8_t id) - returns setting value, provided ID of setting.

int set_setting_value_by_id(uint8_t id, uint8_t *data, uint8_t len) - sets value of setting, provided setting id, new value in form of a byte array and its length. Function returns 0 if ok and -1 if error in provided length.

settings_def.c

For all settings defined in settings.json, structs of appropriate type are auto-generated and initialised with provided data. Main_settings struct is initialised with generated setting structures.

Described functions definitions are auto-generated.

settings.json

Settings, values, commands and messages are determined by the settings.json structure, that is parsed in build time to several .h and .c files, as described below.

It contains the following main fields:

• fw_version

  • major

  • minor

• hardware

  • type - firmware type, for example "wisentedge_nrf52840"

  • version
• settings

  • port - port on which settings are sent and received from

  • type - settings type, based on tracker type
• commands

  • port - port on which commands are sent and received from

  • commands of the form:
• values

  • port - port on which settings are sent and received from

  • values of the form:
• messages

  • messages of the form:

  • message_name

Python parser

Python parser py2h.py and validation script validate_data.py are used to convert settings.json file to c files.

In particular the following files are generated:

• hardware_def.h - containing only definitions from "hardware" field

• settings_def.h and settings_def.c - containing settings structure and auto-generated functions for access and writing to structure

All auto-generated files are equipped with /* AUTOGENERATED FILE - DO NOT MODIFY! */ comment. Sections below describe content of each generated file and helping files.

Since settings and values are stored in nvs storage in byte array form, as well they are sent via LoRa and BLE messages, functions are used to convert byte arrays to data data format used in firmware and back.

Provided functions for byte array to variable type conversion:

• uint32_t bytes_to_uint32_t(uint8_t bytes)

commands_def.h

Defines

Auto-generated defines for all command ID-s. Based on command ID, command is executed in firmware

Global variables

command_settings, containing commands message port define.

Initialisation

Function int init_settings(void), initialises the settings module. It first initialises nvs storage system by calling int nvs_storage_init() and upon success updates all values and settings from nvs storage by calling int update_all_from_nvs().

Status form

Status can consit of several building blocks, defined by FW and tracker type. Each building block is a byte array, where each byte reperesents a values as defined in governing status structre.

Total status cannot exceed 24 - DEVICE_NAME_LEN bytes, as this is the maximum length of BLE advertisment packet. Currently max length is set to 19 bytes.

Main status

Main building block is defined by statusData_t struct:

that can be compressed in byte array by

Individual values are defined as:

• reset_cause - TBD

• system_functions_errors - TBD

• battery = (battery_mV - 2500)/10

Total length of main status part is 9 bytes.

LR status

If #define STATUS_LR is enabled, additional LR chip status block is added.

where:

• satellites - nr. of satellites used in last LR fix

• last_fix - TBD

Total length of LR buildning block is 2 bytes.

UBLOX status

If #define STATUS_UBLOX is enabled, additional UBLOX chip status block is added.

where:

• lat - latitude defined as:

  • lat[0] = (lat+90)*1000 >> 16

  • lat[1] = (lat+90)*1000 >> 8

Total length of UBLOX status is 8 bytes.

Functions

Get status

To obtain new status message for either BLE advertisement or LR status send, int get_status_message(uint8_t *message, uint8_t max_len) function updates all values with int update_status_message(bool lr_status, bool ublox_status) function and returns message length.

max_len can be passed as an argument, as maximal length of message depends on the send format. If status message is too long, only max_len message will be returned.

messages_def.h

Defines

Auto-generated defines for all messages ID-s. Based on message ID, appropriate message is composed and returend in firmware. All defines are of the form MSG_XXX_ID.

Main messages

main_messages struct is auto-generated to contain all messages of cmd_message struct type as defined in settings.json file. In addition to message structs containing different message forms, it contains:

• n_values - number of values

• messages_id - array containing all messages ids

• messages_length - array containing all messages lengths

Global variables

Main_messages is global main_messages struct, accessible in all threads and modules that contains all defined message types.

Structure is ilustrated on the diagram below and further explained in the following sections.

values_def.h

Main values

main_values struct is auto-generated to contain all values as defined in settings.json file. In addition to value structs containing settings, it contains:

• n_values - number of values

• values_id - array containing all values ids

• values_length - array containing all values lengths

Values are defined using same values structs as are used for settings and defined in settings_types.h.

Global variables

Main_values is global main_values struct, accessible in all threads and modules that contains all tracker functionality values.

Values_settings is global values_settings struct , accessible in all threads and modules that contains settings for receiving and sending values.

Functions

void *get_value_struct_by_id(uint8_t id) - returns value struct, provided ID of value.

int get_value_by_id(uint8_t id, uint8_t *data) - returns value from the value struct, provided ID of value.

int set_value_by_id(uint8_t id, uint8_t *data, uint8_t len) - sets value, provided value id, new value in form of a byte array and its length. Function returns 0 if ok and -1 if error in provided length.

values_def.c

For all values defined in settings.json, structs of appropriate type are auto-generated and initialised with provided data. Main_values struct is initialised with generated values structures.

Described functions definitions are auto-generated.

Defines

Values and settings are stored in NVS system by their assigned ID. IDs are ordered as follows:

• Each setting, defined in Main_settings struc is stored by setting ID, defined in Settings.JSON file.

  • Basic settings IDs 0x01 - 0x0F

  • Advanced settings IDs 0x11 - 0x9F

• Other values that needs to be permanently stored for fimware operation are shifted for 8 bits and start with 0x0100.

nvs_storage.h contains list of stored values IDs, that are not part of Main_settings:

• STORAGE_unix_time 0x0100

• STORAGE_latitude 0x0101

• STORAGE_longitude 0x0102

Initialisation

NVS storage is initialised with int nvs_storage_init(void) function, returning 0 on success or negative error code.

Functions

Clearing

To clear whole NVS system, int nvs_storage_clear(void) function is used. To delete only single entry by ID int nvs_storage_delete(uint16_t id) can be used.

Reading and writing

To read from NVS by value ID int nvs_storage_read(uint16_t id, const void *data, size_t len) function returns 0 on sucess.

To write to NVS storage int nvs_storage_write(uint16_t id, const void *data, size_t len) function attempts to write new or existing value.