1 # u-blox 9 positioning receivers configuration library and tool
3 Copyright (c) 2020-2021 Philippe Kehl (flipflip at oinkzwurgl dot org)
5 [https://oinkzwurgl.org/hacking/ubloxcfg](https://oinkzwurgl.org/hacking/ubloxcfg)
7 This implements a library (API) do deal with the new configuration interface introduced in u-blox 9 positioning
10 A command line `cfgtool` is provided to configure a receiver from the configuration defined in a human-readable
11 configuration file, as well as a few other functions.
13 The tool uses a number of small libraries (a UBX/NMEA/RTCM3 message parser, a serial port library, a receiver control
14 library, and some other things), which could be useful for other projects.
16 The configuration library is thread-safe, free of dynamic memory allocation and written in c (ISO C99 with no further
19 The configuration tool and the other libraries use some gcc/libc stuff ("GNU99").
21 This is tested in Linux ([GCC](https://gcc.gnu.org/)). It should work in Windows ([Mingw-w64](http://mingw-w64.org)).
23 [](/../../actions)
29 Note that this probably only works when building on Linux.
31 To build and run the tests:
37 To build the command line tool:
43 To build the API documentation:
49 To build the tests and the tool for Windows:
56 To get a list of all build targets:
62 See the [`Makefile`](./Makefile) for details.
64 You may need to install some dependencies:
67 sudo apt-get install gcc gcc-multilib perl libpath-tiny-perl libdata-float-perl mingw-w64 doxygen
72 GCC for Windows is available from [mingw-w64.org](http://mingw-w64.org/doku.php).
73 Since you might need Perl to generate the configuration definitions (see below) you could also use the
74 GCC that comes with [Strawberry Perl](http://strawberryperl.com/).
76 Depending on the availability of other tools (make, rm, etc.) on your system you will be able to use the Makefile.
78 To manually compile, start a Strawberry Perl shell, navigate to the source code, and use this command to compile:
81 gcc -o output/cfgtool.exe ubloxcfg*.c cfgtool*.c ff*.c crc*.c
84 ### Building as a library (Linux)
86 Parts of this can be compiled as a shared library:
90 sudo make install-library # for installing in /usr/local, or:
91 make install-library LIBPREFIX=/tmp/some/where
93 ## Configuration definitions
95 The definitions for the configuration items (parameters) have been taken from u-blox manuals and converted into a JSON
96 file (with comments): [`ubloxcfg.json`](./ubloxcfg.json).
98 The [`ubloxcfg_gen.pl`](./ubloxcfg_gen.pl) script converts this to c source code: [`ubloxcfg_gen.h`](./ubloxcfg_gen.h)
99 and [`ubloxcfg_gen.c`](./ubloxcfg_gen.c).
101 ## Configuration library
103 The configuration library provides the following:
105 * Type definitions for configuration items (size, data types, IDs)
106 * Functions to look up information on a configuration item (by name, by ID)
107 * Functions to help configuring output message rates.
108 * Helper macros to define lists of key-value pairs
109 * Functions to encode lists of key-value pairs into configuration data (and the reverse)
110 * Functions to stringify configuration items
111 * A function to convert strings into values
113 See [`ubloxcfg.h`](./ubloxcfg.h) or the generated HTML documentation for details and examples.
117 The `cfgtool` command line tool can do the following:
119 * Configure a receiver from a configuration text file
120 * Receiver connection on local serial ports, remote raw TCP/IP ports or telnet (inc. RFC2217) connections
121 * Retrieve configuration from a receiver
122 * Convert a config text file into UBX-CFG-VALSET messages, output as binary UBX messages, u-center compatible hex
126 Run `cfgtool -h` or see [`cfgtool.txt`](./cfgtool.txt) for more information.
130 * Configuration library (`ubloxcfg*.[ch]`): GNU Lesser General Public License (LGPL), see [`COPYING.LESSER`](./COPYING.LESSER)
131 * Configuration tool (`cfgtool*.[ch]`) and the other libraries (`ff_*.[ch]`): GNU General Public License (GPL), see [`COPYING`](./COPYING)
132 * Various third-party code comes with its own license, see [`3rdparty/`](./3rdparty) and below
134 See the individual source files and scripts for details.
138 The tool uses the following third-party code:
140 * _CRC-24Q_ routines from [https://gitlab.com/gpsd/](https://gitlab.com/gpsd/)
141 See the source code ([`crc24q.c`](./crc24q.c)) and license ([`crc24q.COPYING`](./crc24q.COPYING)).
145 * Document ff_* better.
146 * Fix FIXMEs and TODOs. :)