ubloxcfg
u-blox 9 configuration helpers
Configuration data

Data Structures

union  UBLOXCFG_VALUE_u
 Configuration value storage (s.a. UBLOXCFG_TYPE_t) More...
 
struct  UBLOXCFG_KEYVAL_s
 Key-value pair. More...
 

Macros

#define UBLOXCFG_KEYVAL_ANY(name, value)
 Initialiser for a UBLOXCFG_KEYVAL_t for any type. More...
 
#define UBLOXCFG_KEYVAL_ENU(name, value)
 Initialiser for a UBLOXCFG_KEYVAL_t for enum types. More...
 
#define UBLOXCFG_KEYVAL_MSG(msg, port, rate)
 Initialiser for UBLOXCFG_KEYVAL_t for output message rate. More...
 
#define UBLOXCFG_MAX_KEYVAL_STR_SIZE
 Maximum size (= length + 1) for key-value stringification.
 

Typedefs

typedef union UBLOXCFG_VALUE_u UBLOXCFG_VALUE_t
 Configuration value storage (s.a. UBLOXCFG_TYPE_t)
 
typedef struct UBLOXCFG_KEYVAL_s UBLOXCFG_KEYVAL_t
 Key-value pair.
 

Functions

bool ubloxcfg_makeData (uint8_t *data, const int size, const UBLOXCFG_KEYVAL_t *keyVal, const int nKeyVal, int *dataSize)
 Configuration data from key-value list. More...
 
bool ubloxcfg_parseData (const uint8_t *data, const int size, UBLOXCFG_KEYVAL_t *keyVal, const int maxKeyVal, int *nKeyVal)
 Key-value list from configuration data. More...
 
const char * ubloxcfg_typeStr (UBLOXCFG_TYPE_t type)
 Stringify item type. More...
 
bool ubloxcfg_stringifyValue (char *str, const int size, const UBLOXCFG_TYPE_t type, const UBLOXCFG_ITEM_t *item, const UBLOXCFG_VALUE_t *val)
 Stringify item value. More...
 
bool ubloxcfg_splitValueStr (char *str, char **valueStr, char **prettyStr)
 Split stringified value string. More...
 
bool ubloxcfg_stringifyKeyVal (char *str, const int size, const UBLOXCFG_KEYVAL_t *keyVal)
 Stringify key-value pair (for debugging) More...
 
bool ubloxcfg_valueFromString (const char *str, const UBLOXCFG_TYPE_t type, const UBLOXCFG_ITEM_t *item, UBLOXCFG_VALUE_t *value)
 Convert string to value. More...
 

Detailed Description

Macro Definition Documentation

◆ UBLOXCFG_KEYVAL_ANY

#define UBLOXCFG_KEYVAL_ANY (   name,
  value 
)

Initialiser for a UBLOXCFG_KEYVAL_t for any type.

Parameters
[in]nameThe name of the configuration item (with underscores instead of minus, e.g. CFG_NAVSPG_FIXMODE)
[in]valueThe value (of appropriate type, e.g. 1)
Returns
The UBLOXCFG_KEYVAL_t initialiser

Example

const UBLOXCFG_KEYVAL_t keyVal[] =
{
UBLOXCFG_KEYVAL_ANY( CFG_NAVSPG_INIFIX3D, true ), // Set CFG-NAVSPG-INIFIX3D to true
UBLOXCFG_KEYVAL_ANY( CFG_NAVSPG_WKNROLLOVER, 2099 ) // Set CFG-NAVSPG-WKNROLLOVER to 2099
};
#define UBLOXCFG_KEYVAL_ANY(name, value)
Initialiser for a UBLOXCFG_KEYVAL_t for any type.
Definition: ubloxcfg.h:257
Key-value pair.
Definition: ubloxcfg.h:236

Definition at line 257 of file ubloxcfg.h.

◆ UBLOXCFG_KEYVAL_ENU

#define UBLOXCFG_KEYVAL_ENU (   name,
  value 
)

Initialiser for a UBLOXCFG_KEYVAL_t for enum types.

Parameters
[in]nameThe name of the configuration item (with underscores instead of minus, e.g. CFG_NAVSPG_FIXMODE)
[in]valueThe name of the enum value (e.g. 2DONLY)
Returns
The UBLOXCFG_KEYVAL_t initialiser

Example

const UBLOXCFG_KEYVAL_t keyVal[] =
{
UBLOXCFG_KEYVAL_ENU( CFG_NAVSPG_FIXMODE, AUTO ), // Set CFG-NAVSPG-FIXMODE to AUTO (= 3)
//UBLOXCFG_KEYVAL_ANY( CFG_NAVSPG_FIXMODE, 3 ) // Set CFG-NAVSPG-FIXMODE to 3 (= AUTO)
};
#define UBLOXCFG_KEYVAL_ENU(name, value)
Initialiser for a UBLOXCFG_KEYVAL_t for enum types.
Definition: ubloxcfg.h:275

Definition at line 275 of file ubloxcfg.h.

◆ UBLOXCFG_KEYVAL_MSG

#define UBLOXCFG_KEYVAL_MSG (   msg,
  port,
  rate 
)

Initialiser for UBLOXCFG_KEYVAL_t for output message rate.

Parameters
[in]msgThe name of the message (with underscores instead of minus, e.g. UBX_NAV_PVT)
[in]portThe port (UART1, UART2, SPI, I2C or USB)
[in]rateThe message rate (0..255)
Returns
The UBLOXCFG_KEYVAL_t initialiser

Example

const UBLOXCFG_KEYVAL_t keyVal[] =
{
// Set UBX-NAV-PVT output rate to 1 on port UART1
UBLOXCFG_KEYVAL_MSG( UBX_NAV_PVT, UART1, 1),
// Set UBX-MON-COMMS output rate to 5 on port USB
UBLOXCFG_KEYVAL_MSG( UBX_MON_COMMS, USB, 5)
// Disable NMEA-0183-RMC message on port UART2
UBLOXCFG_KEYVAL_MSG( NMEA_0183_RMC, UART2, 0 )
};
#define UBLOXCFG_KEYVAL_MSG(msg, port, rate)
Initialiser for UBLOXCFG_KEYVAL_t for output message rate.
Definition: ubloxcfg.h:298

Definition at line 298 of file ubloxcfg.h.

Function Documentation

◆ ubloxcfg_makeData()

bool ubloxcfg_makeData ( uint8_t *  data,
const int  size,
const UBLOXCFG_KEYVAL_t keyVal,
const int  nKeyVal,
int *  dataSize 
)

Configuration data from key-value list.

Generates binary configuration data (e.g. for UBX-CFG-VALSET message) from a list of key-value pairs.

Parameters
[out]dataBuffer to write the binary configuration data to
[in]sizeBuffer size (maximum size that can be used)
[in]keyValList of key-value pairs
[in]nKeyValNumber of key-value pairs
[out]dataSizeActually used size in data buffer
Returns
true if data buffer was big enough to fit all key-value pairs, false otherwise (in which case neither data nor dataSize are valid)

An empty list (nKeyVal = 0) is a valid input.

Note
This function does not validate the contents of the passed list of key-value pairs.

Example

const UBLOXCFG_KEYVAL_t keyVal[] =
{
UBLOXCFG_KEYVAL_ANY( CFG_NAVSPG_INIFIX3D, true ),
UBLOXCFG_KEYVAL_ANY( CFG_NAVSPG_WKNROLLOVER, 2099 ),
UBLOXCFG_KEYVAL_ENU( CFG_NAVSPG_FIXMODE, AUTO ),
UBLOXCFG_KEYVAL_MSG( UBX_NAV_PVT, UART1, 1),
UBLOXCFG_KEYVAL_MSG( UBX_MON_COMMS, UART1, 5)
};
const int numKeyVal = sizeof(keyVal) / sizeof(*keyVal); // 5
uint8_t data[100];
int size;
const bool res = ubloxcfg_makeData(data, sizeof(data), keyVal, numKeyVal, &size);
if (res)
{
// size = 26
// data[] = { 0x13, 0x00, 0x11, 0x10, 0x01,
// 0x17, 0x00, 0x11, 0x30, 0x33, 0x08,
// 0x11, 0x00, 0x11, 0x20, 0x03,
// 0x07, 0x00, 0x91, 0x20, 0x01,
// 0x50, 0x03, 0x91, 0x20, 0x05 }
}
bool ubloxcfg_makeData(uint8_t *data, const int size, const UBLOXCFG_KEYVAL_t *keyVal, const int nKeyVal, int *dataSize)
Configuration data from key-value list.
Definition: ubloxcfg.c:115

Definition at line 115 of file ubloxcfg.c.

◆ ubloxcfg_parseData()

bool ubloxcfg_parseData ( const uint8_t *  data,
const int  size,
UBLOXCFG_KEYVAL_t keyVal,
const int  maxKeyVal,
int *  nKeyVal 
)

Key-value list from configuration data.

Parses binary configuration data (e.g. from a UBX-CFG-VALGET response) into a list of key-value pairs.

Parameters
[in]dataBuffer to read the binary configuration data from
[in]sizeSize of data buffer
[out]keyValList of key-value pairs to populate
[in]maxKeyValMaximum number of key-value pairs (length of key-value list)
[out]nKeyValNumber of key-value pairs written to list
Returns
true if keyVal was big enough to fit all key-value pairs, false otherwise (in which case neither keyVal nor nKeyVal are valid)

An empty data buffer (dataSize = 0) is a valid input.

Note
This function does not validate the extracted keys.

Example

const uint8_t data[26] =
{
0x13, 0x00, 0x11, 0x10, 0x01, // CFG-NAVSPG-INIFIX3D = 1 (true)
0x17, 0x00, 0x11, 0x30, 0x33, 0x08, // CFG-NAVSPG-WKNROLLOVER = 2099 (0x0833)
0x11, 0x00, 0x11, 0x20, 0x03, // CFG-NAVSPG-FIXMODE = 3 (AUTO)
0x07, 0x00, 0x91, 0x20, 0x01, // CFG-MSGOUT-UBX_NAV_PVT_UART1 = 1
0x50, 0x03, 0x91, 0x20, 0x05 // CFG-MSGOUT-UBX_MON_COMMS_UART1 = 1
};
int numKeyVal;
UBLOXCFG_KEYVAL_t keyVal[20];
const bool res = ubloxcfg_parseData(data, sizeof(data), keyVal, sizeof(keyVal)/sizeof(*keyVal), &numKeyVal);
if (res)
{
// numKeyVal = 5
// keyVal[0].id = UBLOXCFG_CFG_NAVSPG_INIFIX3D_ID, keyVal[0].val.L = true
// keyVal[1].id = UBLOXCFG_CFG_NAVSPG_WKNROLLOVER_ID, keyVal[1].val.U2 = 2099
// keyVal[2].id = UBLOXCFG_CFG_NAVSPG_FIXMODE_ID, keyVal[2].val.E1 = 3 (= AUTO)
// keyVal[3].id = UBLOXCFG_CFG_MSGOUT_UBX_NAV_PVT_UART1_ID, keyVal[3].val.U1 = 1
// keyVal[4].id = UBLOXCFG_CFG_MSGOUT_UBX_MON_COMMS_UART1_ID, keyVal[4].val.U1 = 1
}
bool ubloxcfg_parseData(const uint8_t *data, const int size, UBLOXCFG_KEYVAL_t *keyVal, const int maxKeyVal, int *nKeyVal)
Key-value list from configuration data.
Definition: ubloxcfg.c:209

Definition at line 209 of file ubloxcfg.c.

◆ ubloxcfg_typeStr()

const char* ubloxcfg_typeStr ( UBLOXCFG_TYPE_t  type)

Stringify item type.

Parameters
[in]typeType
Returns
Returns a string with the item type ("L", "U1", etc.) resp. NULL if the type is none of UBLOXCFG_TYPE_e.

Definition at line 331 of file ubloxcfg.c.

◆ ubloxcfg_stringifyValue()

bool ubloxcfg_stringifyValue ( char *  str,
const int  size,
const UBLOXCFG_TYPE_t  type,
const UBLOXCFG_ITEM_t item,
const UBLOXCFG_VALUE_t val 
)

Stringify item value.

Parameters
[out]strString to format with the value
[in]sizeSize of the str buffer
[in]typeType
[in]itemItem (or NULL)
[in]valConfiguration item value
Returns
Returns true if the value was successfully formatted, false otherwise (size too small, ...)

Constant names will be added for L type, and, where available, for X and E type if item is given.

This function does not apply item scale factors nor does it add item units to the formatted string.

The stringification is as follows:

  • L type: "0 (false)" or "1 (true)"
  • U types: "0", "42", "8190232132"
  • I types: "0", "-42", "3423443"
  • X types (FIRST=0x01, LAST=0x80): "0x81 (FIRST|LAST)", "0x7c (n/a)", "0xff (FIRST|LAST|0x7c)", "0x00 (n/a)"
  • E types (ONE=1, TWO=2): "1 (ONE)", "2 (TWO)", "3 (n/a)"
  • R types: "0", "1", "0.5", "1.25e-24"
  • Unknown items all stringify to X type, i.e. "0x04 (n/a)", "0x1234 (n/a)", etc.

That is, the string starts with the numeric value, followed by one space character, followed by a pretty-printed value in brackets (where useful).

The str buffer should be reasonably big (UBLOXCFG_MAX_KEYVAL_STR_SIZE), esp. for stringification of E and X types.

Definition at line 357 of file ubloxcfg.c.

◆ ubloxcfg_splitValueStr()

bool ubloxcfg_splitValueStr ( char *  str,
char **  valueStr,
char **  prettyStr 
)

Split stringified value string.

Parameters
[in]strThe string formatted by ubloxcfg_stringifyValue()
[out]valueStrString with only the value
[out]prettyStrString with only the pretty part (or NULL)
Returns
true if successfully split, in which case str is tainted

The str is split on the space character. A "(n/a)" pretty-printed value in str is ignored and prettyStr is set to NULL. I.e. "value (pretty)" becomes "value" and "pretty". "value" or "value (n/a)" become "value" and NULL.

Definition at line 544 of file ubloxcfg.c.

◆ ubloxcfg_stringifyKeyVal()

bool ubloxcfg_stringifyKeyVal ( char *  str,
const int  size,
const UBLOXCFG_KEYVAL_t keyVal 
)

Stringify key-value pair (for debugging)

Parameters
[out]strString to format
[in]sizeSize of the str buffer
[in]keyValKey-value pair
Returns
Returns true if the value was successfully formatted, false otherwise (size too small, ...)

The str buffer should be reasonably big (UBLOXCFG_MAX_KEYVAL_STR_SIZE), esp. for stringification of E and X types.

Example

const UBLOXCFG_KEYVAL_t keyVal[] =
{
UBLOXCFG_KEYVAL_ANY( CFG_NAVSPG_INIFIX3D, true ),
UBLOXCFG_KEYVAL_ANY( CFG_NAVSPG_WKNROLLOVER, 2099 ),
UBLOXCFG_KEYVAL_ENU( CFG_NAVSPG_FIXMODE, AUTO ),
UBLOXCFG_KEYVAL_ANY( CFG_NAVSPG_INFIL_MINCNO, 30 ),
UBLOXCFG_KEYVAL_ANY( CFG_NAVSPG_OUTFIL_PDOP, 20 ),
UBLOXCFG_KEYVAL_ANY( CFG_NAVSPG_CONSTR_ALT, 234 ),
UBLOXCFG_KEYVAL_MSG( UBX_NAV_PVT, UART1, 1 ),
{ .id = 0x30fe0ff3, .val = { .U2 = 48879 } }
};
const int numKeyVal = sizeof(keyVal) / sizeof(*keyVal); // 7
for (int ix = 0; ix < numKeyVal; ix++)
{
char str[200];
const bool res = ubloxcfg_stringifyKeyVal(str, sizeof(str), &keyVal[ix]);
if (res)
{
printf("keyVal[%d]: %s\n", ix, str);
// keyVal[0]: CFG-NAVSPG-INIFIX3D (0x10110013, L) = 1 (true)
// keyVal[1]: CFG-NAVSPG-WKNROLLOVER (0x30110017, U2) = 2099
// keyVal[2]: CFG-NAVSPG-FIXMODE (0x20110011, E1) = 3 (AUTO)
// keyVal[3]: CFG-NAVSPG-INFIL_MINCNO (0x201100a3, U1) = 30 [dBHz]
// keyVal[4]: CFG-NAVSPG-OUTFIL_PDOP (0x301100b1, U2) = 20 [0.1]
// keyVal[5]: CFG-NAVSPG-CONSTR_ALT (0x401100c1, I4) = 234 [0.01m]
// keyVal[6]: CFG-MSGOUT-UBX_NAV_PVT_UART1 (0x20910007, U1) = 1
// keyVal[7]: CFG-?-? (0x30fe0ff3, ?2) = 0xbeef
}
}
bool ubloxcfg_stringifyKeyVal(char *str, const int size, const UBLOXCFG_KEYVAL_t *keyVal)
Stringify key-value pair (for debugging)
Definition: ubloxcfg.c:570

Definition at line 570 of file ubloxcfg.c.

◆ ubloxcfg_valueFromString()

bool ubloxcfg_valueFromString ( const char *  str,
const UBLOXCFG_TYPE_t  type,
const UBLOXCFG_ITEM_t item,
UBLOXCFG_VALUE_t value 
)

Convert string to value.

Parameters
[in]strString to convert
[in]typeType of value
[in]itemItem (or NULL)
[out]valueValue
Returns
true if string successfully converted, false otherwise

The following conversions are accepted:

  • The L type can be converted from: "true", "false" or any decimal, hexadecimal or octal string that translate to the value 1 or 0.
  • The U and X types can be converted from decimal, hexadecimal or octal strings.
  • The I and E types can be converted from decimal or hexadecimal strings.
  • When an item is given for E and X types, converting constant names (see below) will be attempted first.
  • E type constants are single words, such as FOO.
  • X type constants are one or more words or hexadecimal strings separated by a |, e.g.: FOO, FOO|BAR, FOO|BAR|0x05, or 0x01|0x04|0x20
Note
The input str must not contain any characters that are not part of the value (for example leading or trailing whitespace).

Examples

ubloxcfg_valueFromString("true", UBLOXCFG_TYPE_L, NULL, &value); // value.L = true
ubloxcfg_valueFromString("0", UBLOXCFG_TYPE_L, NULL, &value); // value.L = false
ubloxcfg_valueFromString("0x2a", UBLOXCFG_TYPE_U1, NULL, &value); // value.U1 = 42
bool ubloxcfg_valueFromString(const char *str, UBLOXCFG_TYPE_t type, const UBLOXCFG_ITEM_t *item, UBLOXCFG_VALUE_t *value)
Convert string to value.
Definition: ubloxcfg.c:670
@ UBLOXCFG_TYPE_L
One bit logical (0 = false, 1 = true)
Definition: ubloxcfg.h:96
@ UBLOXCFG_TYPE_U1
One byte unsigned, little-endian (uint8_t)
Definition: ubloxcfg.h:79
Configuration value storage (s.a. UBLOXCFG_TYPE_t)
Definition: ubloxcfg.h:211
ubloxcfg_valueFromString("AUTO", item->type, item, &value); // value.E1 = 3
#define UBLOXCFG_CFG_NAVSPG_FIXMODE_ID
ID of CFG-NAVSPG-FIXMODE.
const UBLOXCFG_ITEM_t * ubloxcfg_getItemById(const uint32_t id)
Get configuration item info by key ID.
Definition: ubloxcfg.c:69
Configuration item.
Definition: ubloxcfg.h:114
UBLOXCFG_TYPE_t type
Storage type.
Definition: ubloxcfg.h:116
ubloxcfg_valueFromString("FIRST|LAST", item->type, item, &value); // value.X1 = 0x81
#define UBLOXCFG_CFG_UBLOXCFGTEST_X1_ID
ID of CFG-UBLOXCFGTEST-X1.

Definition at line 670 of file ubloxcfg.c.