Documentation update only: misc.

u-blox · Jan 26, 2024 · 03c0fc4 · 03c0fc4
1 parent d86f0c6
commit 03c0fc4
Show file tree

Hide file tree

Showing 20 changed files with 74 additions and 54 deletions.
diff --git a/README.md b/README.md
@@ -79,7 +79,7 @@ Peripherals are u-blox modules which accept commands (e.g. AT-commands) over a s
 
 
 <sup>3: Through the u-blox [CellLocate](https://www.u-blox.com/en/product/celllocate) mobile network-based location service.</sup><br />
-<sup>4: Beta support: please **add** `short_range_gen2` to the `UBXLIB_FEATURES` variable in your `make` or `CMake` file when building `ubxlib` for NORA-W36; NORA-W36 comes with a second generation uConnectExpress, please see the release notes for NORA-W36 for the supported features.</sup>
+<sup>4: Beta support: please **add** `short_range_gen2` to the `UBXLIB_FEATURES` variable in your `make` or `CMake` file when building `ubxlib` for NORA-W36; NORA-W36 comes with a second generation u-connectExpress, please see the release notes for NORA-W36 for the supported features.</sup>
 
 # Structure of `ubxlib`
 The APIs for each type of u-blox module can be found in the relevant directory (e.g. [cell](/cell) for cellular modules and [ble](/ble)/[wifi](/wifi) for BLE/Wi-Fi modules).  The [common](/common) directory contains APIs and 'helper' modules that are shared by u-blox modules, most importantly the [device](/common/device) API, the [network](/common/network) API and the [sockets](/common/sockets) API.  All APIs are documented in the API header files.

diff --git a/ble/README.md b/ble/README.md
@@ -28,13 +28,13 @@ It is not in the scope of this API to support the full range short range module
 # Usage
 The [api](api) directory contains the files that define the BLE APIs, each API function documented in its header file.  In the [src](src) and [src/gen2](src/gen2) directories you will find the implementation of the APIs and in the [test](test) directory the tests for the APIs that can be run on any platform.
 
-# uConnectExpress For NORA-W36 And Beyond
-`ubxlib` relies on uConnectExpress, running on the short-range module and providing the AT interface to this MCU.  While `ubxlib` does not rely on a particular version of uConnectExpress, NORA-W3 and later modules are provided with a second generation of uConnectExpress which requires the `ubxlib` code in the [src/gen2](src/gen2) directory rather that in the [src](src) directory.
+# u-connectExpress For NORA-W36 And Beyond
+`ubxlib` relies on u-connectExpress, running on the short-range module and providing the AT interface to this MCU.  While `ubxlib` does not rely on a particular version of u-connectExpress, NORA-W3 and later modules are provided with a second generation of u-connectExpress which requires the `ubxlib` code in the [src/gen2](src/gen2) directory rather that in the [src](src) directory.
 
 To use the [src/gen2](src/gen2) code, please **add** `short_range_gen2` to the `UBXLIB_FEATURES` variable in your `make` or `CMake` file, e.g.:
 
 ```
 UBXLIB_FEATURES=cell gnss short_range short_range_gen2
 ```
 
-The versions of uConnectExpress that we test with are listed in the short-range [test](/common/short_range/test) directory.
+The versions of u-connectExpress that we test with are listed in the short-range [test](/common/short_range/test) directory.
diff --git a/ble/api/u_ble_module_type.h b/ble/api/u_ble_module_type.h
@@ -45,7 +45,7 @@
 /** The possible types of BLE module.
  *
  * IMPORTANT: if you are using U_BLE_MODULE_TYPE_NORA_W36, which comes
- * with a second generation of uConnectExpress, you MUST add
+ * with a second generation of u-connectExpress, you MUST add
  * short_range_gen2 to the UBXLIB_FEATURES variable in your make or CMake
  * file when building ubxlib.  For instance:
  *

diff --git a/ble/src/README.md b/ble/src/README.md
@@ -1,4 +1,4 @@
 # IMPORTANT
-When `short_range_gen2` is added to the `UBXLIB_FEATURES` variable in your `make` or `CMake` file (e.g. for the next generation uConnectExpress used by NORA-W36), NONE OF THE SOURCE FILES IN THIS DIRECTORY are used.
+When `short_range_gen2` is added to the `UBXLIB_FEATURES` variable in your `make` or `CMake` file (e.g. for the next generation u-connectExpress used by NORA-W36), NONE OF THE SOURCE FILES IN THIS DIRECTORY are used.
 
 Please see the files in the [gen2](gen2) sub-directory instead.
diff --git a/cell/api/u_cell_module_type.h b/cell/api/u_cell_module_type.h
@@ -91,7 +91,14 @@ typedef enum {
     U_CELL_MODULE_TYPE_LENA_R8 = 8,
     // Add any new module types here, before U_CELL_MODULE_TYPE_ANY, assigning
     // them to specific values.
-    U_CELL_MODULE_TYPE_ANY,
+    U_CELL_MODULE_TYPE_ANY, /**< when this module type is used the code will
+                                 interrogate the module and chose the correct
+                                 module type by itself; should this fail, for
+                                 example because you are using a module type which
+                                 is sufficiently close to a supported module type
+                                 to work but the ID string it returns is too
+                                 different to be detected, then you should chose
+                                 the specific module type you want instead. */
     U_CELL_MODULE_TYPE_MAX_NUM
 } uCellModuleType_t;
 

diff --git a/common/location/api/u_location.h b/common/location/api/u_location.h
@@ -133,11 +133,11 @@ typedef enum {
     U_LOCATION_TYPE_CLOUD_CELL_LOCATE = 2, /**< supported on cellular network
                                                 instances only. */
     U_LOCATION_TYPE_CLOUD_GOOGLE = 3, /**< supported on Wi-Fi network instances
-                                           with uConnectExpress version 5. */
+                                           with u-connectExpress version 5. */
     U_LOCATION_TYPE_CLOUD_SKYHOOK = 4, /**< supported on Wi-Fi network instances
-                                            with uConnectExpress version 5. */
+                                            with u-connectExpress version 5. */
     U_LOCATION_TYPE_CLOUD_HERE = 5,  /**< supported on Wi-Fi network instances
-                                          with uConnectExpress version 5. */
+                                          with u-connectExpress version 5. */
     U_LOCATION_TYPE_CLOUD_CLOUD_LOCATE = 6,  /**< supported on cellular and Wi-Fi
                                                   network instances. */
     U_LOCATION_TYPE_MAX_NUM

diff --git a/common/security/test/u_security_credential_test.c b/common/security/test/u_security_credential_test.c
@@ -321,10 +321,10 @@ U_PORT_TEST_FUNCTION("[securityCredential]", "securityCredentialTest")
             U_TEST_PRINT_LINE_X_Y("expiration %d UTC.", x, z, credential.expirationUtc);
             if (strcmp(credential.name, "ubxlib_test_cert") == 0) {
                 U_PORT_TEST_ASSERT(credential.type == U_SECURITY_CREDENTIAL_CLIENT_X509);
-                // Used to check the subject here but V5 uConnectExpress doesn't
+                // Used to check the subject here but V5 u-connectExpress doesn't
                 // give what we would expect (the subject of ubxlib_test_cert should
-                // be "ubxlib client" but uConnectExpress V5 has it as "CN=ubxlib ca",
-                // while earlier version of uConnectExpress don't report it at all),
+                // be "ubxlib client" but u-connectExpress V5 has it as "CN=ubxlib ca",
+                // while earlier version of u-connectExpress don't report it at all),
                 // so we can't check it
                 if (credential.expirationUtc != 0) {
                     U_PORT_TEST_ASSERT(credential.expirationUtc == U_SECURITY_CREDENTIAL_TEST_X509_EXPIRATION_UTC);
@@ -478,10 +478,10 @@ U_PORT_TEST_FUNCTION("[securityCredential]", "securityCredentialTest")
                 U_TEST_PRINT_LINE_X_Y("expiration %d UTC.", x, z, credential.expirationUtc);
                 if (strcmp(credential.name, "ubxlib_test_cert") == 0) {
                     U_PORT_TEST_ASSERT(credential.type == U_SECURITY_CREDENTIAL_CLIENT_X509);
-                    // Used to check the subject here but V5 uConnectExpress doesn't
+                    // Used to check the subject here but V5 u-connectExpress doesn't
                     // give what we would expect (the subject of ubxlib_test_cert should
-                    // be "ubxlib client" but uConnectExpress V5 has it as "CN=ubxlib ca",
-                    // while earlier version of uConnectExpress don't report it at all),
+                    // be "ubxlib client" but u-connectExpress V5 has it as "CN=ubxlib ca",
+                    // while earlier version of u-connectExpress don't report it at all),
                     // so we can't check it
                     if (credential.expirationUtc != 0) {
                         U_PORT_TEST_ASSERT(credential.expirationUtc == U_SECURITY_CREDENTIAL_TEST_X509_EXPIRATION_UTC);

diff --git a/common/short_range/README.md b/common/short_range/README.md
@@ -3,23 +3,23 @@ This directory contains the short-range APIs, covering both Wi-Fi and BLE contro
 
 This API relies upon either [common/at_client](/common/at_client) or the `ucxclient` under [src/gen2](src/gen2) (see below) to send commands to and parse responses received from an external Wi-Fi/BLE module.
 
-The operation of `ubxlib` does not rely on a particular version of uConnectExpress; the versions that we test with are listed in the [test](test) directory.
+The operation of `ubxlib` does not rely on a particular version of u-connectExpress; the versions that we test with are listed in the [test](test) directory.
 
 # Usage
 The [api](api) directory contains the files that define the short range APIs, each API function documented in its header file.  In the [src](src) and [src/gen2](src/gen2) directories you will find the implementation of the APIs and in the [test](test) directory the tests for the APIs that can be run on any platform.
 
-# uConnectExpress For NORA-W36 And Beyond
-`ubxlib` relies on uConnectExpress, running on the short-range module and providing the AT interface to this MCU.  While `ubxlib` does not rely on a particular version of uConnectExpress, NORA-W3 and later modules are provided with a second generation of uConnectExpress which requires the `ubxlib` code in the [src/gen2](src/gen2) directory rather that in the [src](src) directory.
+# u-connectExpress For NORA-W36 And Beyond
+`ubxlib` relies on u-connectExpress, running on the short-range module and providing the AT interface to this MCU.  While `ubxlib` does not rely on a particular version of u-connectExpress, NORA-W3 and later modules are provided with a second generation of u-connectExpress which requires the `ubxlib` code in the [src/gen2](src/gen2) directory rather that in the [src](src) directory.
 
 To use the [src/gen2](src/gen2) code, please **add** `short_range_gen2` to the `UBXLIB_FEATURES` variable in your `make` or `CMake` file, e.g.:
 
 ```
 UBXLIB_FEATURES=cell gnss short_range short_range_gen2
 ```
 
-The versions of uConnectExpress that we test with are listed in the short-range [test](/common/short_range/test) directory.
+The versions of u-connectExpress that we test with are listed in the short-range [test](/common/short_range/test) directory.
 
 ## Implementation Note
-The next generation uConnectExpress for NORA-W36 is quite different to what went before, hence the new implementation files in [src/gen2](src/gen2).  In particular:
+The next generation u-connectExpress for NORA-W36 is quite different to what went before, hence the new implementation files in [src/gen2](src/gen2).  In particular:
 - an entirely new AT parser is used for NORA-W36, NOT [common/at_client](/common/at_client), see the `ucxclient` under [src/gen2](src/gen2); if your application made any direct calls into [common/at_client](/common/at_client) previously then, to have an effect on NORA-W36, the equivalents in the `ucxclient` under [src/gen2](src/gen2) must be called (the existing calls to [common/at_client](/common/at_client) should remain if you are also using a cellular module or a short-range module other than NORA-W36),
 - EDM (Extended Data Mode) is no longer used at all.
diff --git a/common/short_range/api/u_short_range_module_type.h b/common/short_range/api/u_short_range_module_type.h
@@ -45,7 +45,7 @@
 /** The possible types of short range module.
  *
  * IMPORTANT: if you are using U_SHORT_RANGE_MODULE_TYPE_NORA_W36, which
- * comes with a second generation of uConnectExpress, you MUST add
+ * comes with a second generation of u-connectExpress, you MUST add
  * short_range_gen2 to the UBXLIB_FEATURES variable in your make or CMake
  * file when building ubxlib.  For instance:
  *
@@ -73,8 +73,14 @@
 #endif
 // Add any new module types here, before U_SHORT_RANGE_MODULE_TYPE_ANY,
 // and assign specific values
-#define U_SHORT_RANGE_MODULE_TYPE_ANY       10
-
+#define U_SHORT_RANGE_MODULE_TYPE_ANY       10 /**< when this module type is used the code will
+                                                    interrogate the module and chose the correct
+                                                    module type by itself; should this fail, for
+                                                    example because you are using a module type which
+                                                    is sufficiently close to a supported module type
+                                                    to work but the ID string it returns is too
+                                                    different to be detected, then you should chose
+                                                    the specific module type you want instead. */
 #define U_SHORT_RANGE_MODULE_TYPE_INVALID -1
 #define U_SHORT_RANGE_MODULE_TYPE_UNSUPPORTED -2
 

diff --git a/common/short_range/src/README.md b/common/short_range/src/README.md
@@ -1,4 +1,4 @@
 # IMPORTANT
-When `short_range_gen2` is added to the `UBXLIB_FEATURES` variable in your `make` or `CMake` file (e.g. for the next generation uConnectExpress used by NORA-W36), NONE OF THE SOURCE FILES IN THIS DIRECTORY are used.
+When `short_range_gen2` is added to the `UBXLIB_FEATURES` variable in your `make` or `CMake` file (e.g. for the next generation u-connectExpress used by NORA-W36), NONE OF THE SOURCE FILES IN THIS DIRECTORY are used.
 
 Please see the files in the [gen2](gen2) sub-directory instead.
diff --git a/common/short_range/test/README.md b/common/short_range/test/README.md
@@ -1,5 +1,5 @@
-# uConnectExpress Versions
-The uConnectExpress versions that these tests are run on are as follows:
+# u-connectExpress Versions
+The u-connectExpress versions that these tests are run on are as follows:
 
 - NINA-W15: 5.2.2.
-- NORA-W36: uConnectExpress second generation, version 1.0.0.
+- NORA-W36: u-connectExpress second generation, version 1.0.0.
diff --git a/gnss/api/u_gnss_module_type.h b/gnss/api/u_gnss_module_type.h
@@ -62,7 +62,14 @@ typedef enum {
     U_GNSS_MODULE_TYPE_M10 = 2,
     // Add any new module types here, before U_GNSS_MODULE_TYPE_ANY, assigning
     // them to specific values.
-    U_GNSS_MODULE_TYPE_ANY,
+    U_GNSS_MODULE_TYPE_ANY, /**< when this module type is used the code will
+                                 interrogate the module and chose the correct
+                                 module type by itself; should this fail, for
+                                 example because you are using a module type which
+                                 is sufficiently close to a supported module type
+                                 to work but the ID string it returns is too
+                                 different to be detected, then you should chose
+                                 the specific module type you want instead. */
     U_GNSS_MODULE_TYPE_MAX_NUM
 } uGnssModuleType_t;
 

diff --git a/gnss/src/u_gnss_private.h b/gnss/src/u_gnss_private.h
@@ -177,7 +177,7 @@ typedef struct uGnssPrivateMsgReader_t {
     int32_t handle;
     uGnssPrivateMessageId_t privateMessageId;
     void *pCallback; /**< stored as a void * to avoid having to bring
-                          all the types of uGnssTransparentReceiveCallback_t
+                          all the types of uGnssMsgReceiveCallback_t
                           into everything. */
     void *pCallbackParam;
     struct uGnssPrivateMsgReader_t *pNext;

diff --git a/port/platform/common/automation/README.md b/port/platform/common/automation/README.md
@@ -252,4 +252,4 @@ If the commit text does *not* contain a line starting with `test:` (the usual ca
 - If you add a new platform or test suite, add it to [DATABASE.md](DATABASE.md) and make sure that the result is parsed correctly by [u_data.py](./scripts/u_data.py) (e.g. by running `automation.<command>` PyInvoke tasks) from the command-line and checking that everything is correct).
 - If you add a new item in the range 0 to 9 (i.e. a checker with no platform), update [automation.py](./tasks/automation.py) to include it.
 - If you add a new directory OFF THE ROOT of `ubxlib`, i.e. something like `ubxlib/blah`, add it to the `ASTYLE_DIRS` variable of the [u_run_astyle.py](./scripts/u_run_astyle.py) script.
-- When the FW version of a cellular module, or GNSS chip, or uConnectExpress version in the test system is updated, update the `README.md` in the corresponding test directory with that version.
+- When the FW version of a cellular module, or GNSS chip, or u-connectExpress version in the test system is updated, update the `README.md` in the corresponding test directory with that version.
diff --git a/port/platform/zephyr/README.md b/port/platform/zephyr/README.md
@@ -92,6 +92,20 @@ socat /dev/pts/3,echo=0,raw /dev/pts/3,echo=0,raw
 
 ...would loop `/dev/pts/3` (in the example above UART 0) back on itself.
 
+## Additional Notes
+- Always clean the build directory when upgrading to a new `ubxlib` version.
+- You may override or provide conditional compilation flags to CMake without modifying `CMakeLists.txt`.  Do this by setting an environment variable `U_FLAGS`, e.g.:
+
+  ```
+  set U_FLAGS=-DMY_FLAG
+  ```
+
+  ...or:
+
+  ```
+  set U_FLAGS=-DMY_FLAG -DU_CFG_APP_PIN_CELL_ENABLE_POWER=-1
+  ```
+
 # Device Tree
 Zephyr pin choices for any HW peripheral managed by Zephyr (e.g. UART, I2C, SPI, etc.) are made at compile-time in the Zephyr device tree, they cannot be passed into the functions as run-time variables.  Look in the `zephyr/zephyr.dts` file located in your build directory to find the resulting pin allocations for these peripherals.
 
@@ -235,20 +249,6 @@ Notes:
 
 FYI, for transports and GPIOs, what `ubxlib` is trying to get is the HW block number, for example the `0` on the end of `&uart0`; however, there is no way (see [discussion](https://github.com/zephyrproject-rtos/zephyr/issues/67046)), from within C code, to get that `0`, or even `uart0`, those references are all resolved inside the Zephyr device tree parser before any C code is compiled.  This is why the `transport-type` and `pin-xxx` labels, which would naturally just be `phandle` references, e.g. `<&uart0>` and `<gpio1 3 0>`, have to instead be strings and integers.  Should Zephyr provide a mechanism to obtain this information in future then we will adopt it and the properties will become conventional.
 
-## Additional Notes
-- Always clean the build directory when upgrading to a new `ubxlib` version.
-- You may override or provide conditional compilation flags to CMake without modifying `CMakeLists.txt`.  Do this by setting an environment variable `U_FLAGS`, e.g.:
-
-  ```
-  set U_FLAGS=-DMY_FLAG
-  ```
-
-  ...or:
-
-  ```
-  set U_FLAGS=-DMY_FLAG -DU_CFG_APP_PIN_CELL_ENABLE_POWER=-1
-  ```
-
 # PPP-Level Integration With Cellular
 PPP support in Zephyr, at least in Zephyr version 3.4.99, is marked as "experimental": despite the presence of a PAP configuration item, there is no way to configure the authentication mode or the username/password (which are hard-coded in `zephyr/subsys/net/l2/ppp/pap.c`, see function `pap_config_info_add()`) and there doesn't appear to be any code to support CHAP authentication; hence, if your operator requires a user name and password along with the APN, you have no choice but to edit the Zephyr source code.