ubloxcfg
u-blox 9 configuration helpers
README.md
1 # u-blox 9 positioning receivers configuration library and tool
2 
3 Copyright (c) 2020-2021 Philippe Kehl (flipflip at oinkzwurgl dot org)
4 
5 [https://oinkzwurgl.org/hacking/ubloxcfg](https://oinkzwurgl.org/hacking/ubloxcfg)
6 
7 This implements a library (API) do deal with the new configuration interface introduced in u-blox 9 positioning
8 receivers (e.g. [1]).
9 
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.
12 
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.
15 
16 The configuration library is thread-safe, free of dynamic memory allocation and written in c (ISO C99 with no further
17 dependencies).
18 
19 The configuration tool and the other libraries use some gcc/libc stuff ("GNU99").
20 
21 This is tested in Linux ([GCC](https://gcc.gnu.org/)). It should work in Windows ([Mingw-w64](http://mingw-w64.org)).
22 
23 [![CI](/../../workflows/CI/badge.svg?branch=master)](/../../actions)
24 
25 ## Building
26 
27 ### Linux
28 
29 Note that this probably only works when building on Linux.
30 
31 To build and run the tests:
32 
33 ```sh
34 make test
35 ```
36 
37 To build the command line tool:
38 
39 ```sh
40 make cfgtool
41 ```
42 
43 To build the API documentation:
44 
45 ```sh
46 make doc
47 ```
48 
49 To build the tests and the tool for Windows:
50 
51 ```sh
52 make test.exe
53 make cfgtool.exe
54 ```
55 
56 To get a list of all build targets:
57 
58 ```sh
59 make help
60 ```
61 
62 See the [`Makefile`](./Makefile) for details.
63 
64 You may need to install some dependencies:
65 
66 ```sh
67 sudo apt-get install gcc gcc-multilib perl libpath-tiny-perl libdata-float-perl mingw-w64 doxygen
68 ```
69 
70 ### Windows
71 
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/).
75 
76 Depending on the availability of other tools (make, rm, etc.) on your system you will be able to use the Makefile.
77 
78 To manually compile, start a Strawberry Perl shell, navigate to the source code, and use this command to compile:
79 
80 ```
81 gcc -o output/cfgtool.exe ubloxcfg*.c cfgtool*.c ff*.c crc*.c
82 ```
83 
84 ### Building as a library (Linux)
85 
86 Parts of this can be compiled as a shared library:
87 
88 ```sh
89 make libubloxcfg.so
90 sudo make install-library # for installing in /usr/local, or:
91 make install-library LIBPREFIX=/tmp/some/where
92 ```
93 ## Configuration definitions
94 
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).
97 
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).
100 
101 ## Configuration library
102 
103 The configuration library provides the following:
104 
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
112 
113 See [`ubloxcfg.h`](./ubloxcfg.h) or the generated HTML documentation for details and examples.
114 
115 ## Tool
116 
117 The `cfgtool` command line tool can do the following:
118 
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
123  dumps, or c code
124 * And more...
125 
126 Run `cfgtool -h` or see [`cfgtool.txt`](./cfgtool.txt) for more information.
127 
128 ## License
129 
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
133 
134 See the individual source files and scripts for details.
135 
136 ## Third-party code
137 
138 The tool uses the following third-party code:
139 
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)).
142 
143 ## Todo, ideas
144 
145 * Document ff_* better.
146 * Fix FIXMEs and TODOs. :)
147