Documentation update only: misc. tidy-up. (#954)

README.md

@@ -1,7 +1,5 @@
 <img src="/readme_images/ubxlib-logo.svg" width="400">
 
-[![important message](/readme_images/important_msg.svg)](/UPCOMING.md)
-
 # Introduction to `ubxlib`
 This repository contains an add-on to microcontroller and RTOS SDKs for building embedded applications with u-blox products and services. It provides portable C libraries which expose APIs with examples. `ubxlib` supports [u-blox](https://www.u-blox.com) modules with [cellular](https://www.u-blox.com/en/cellular-modules) (2G/3G/4G), [short-range](https://www.u-blox.com/en/short-range-radio-chips-and-modules) (Bluetooth and Wi-Fi) and [positioning](https://www.u-blox.com/en/positioning-chips-and-modules) (GNSS) functionality. The `ubxlib` libraries present high level C APIs for use in customer applications (e.g. connect to a network, open a TCP socket, establish location, etc.) and implements these APIs on selected popular MCUs, also available inside u-blox modules.
 

cell/api/u_cell_file.h

@@ -175,8 +175,8 @@ int32_t uCellFileBlockRead(uDeviceHandle_t cellHandle,
 int32_t uCellFileSize(uDeviceHandle_t cellHandle,
                       const char *pFileName);
 
-/** Delete a file from the file system. If the file does not exist,
- * error will be return.
+/** Delete a file from the file system. If the file does not exist an
+ * error will be returned.
  *
  * @param cellHandle     the handle of the cellular instance.
  * @param[in] pFileName  a pointer to the file name to delete from the

common/location/api/u_location.h

@@ -32,7 +32,7 @@
  * @brief This header file defines the location API, which is designed
  * to determine location using any u-blox module and potentially a
  * cloud service.  These functions are thread-safe with the exception
- * that the network layer should not be deactivated (i.e. with
+ * that the device layer should not be deactivated (i.e. with
  * uDeviceDeinit()) while an asynchronous location request is
  * outstanding.
  */
@@ -248,8 +248,7 @@ typedef struct {
                                      range -100 dBm to 0 dBm. */
 } uLocationAssist_t;
 
-/** Definition of a location.  If you change this, don't forget to change
- * U_LOCATION_DEFAULTS also.
+/** Definition of a location.
  */
 typedef struct {
     uLocationType_t type; /**< the location mechanism that was used. */
@@ -312,7 +311,7 @@ typedef enum {
 /** Get the current location, returning on success or when
  * pKeepGoingCallback returns false, whichever is earlier.
  * uNetworkInterfaceUp() (see the network API) must have been called
- * on the given devHandle for this function to work.
+ * on the given device handle for this function to work.
  *
  * Note that if you have a GNSS chip inside your cellular module
  * (e.g. you have a SARA-R510M8S or SARA-R422M8S) then making a
@@ -339,7 +338,7 @@ typedef enum {
  * @param devHandle               the device handle to use.
  * @param type                    the type of location fix to perform;
  *                                how this can be used depends upon the
- *                                type of networkHandle:
+ *                                type of devHandle:
  *                                - GNSS:     ignored, #U_LOCATION_TYPE_GNSS
  *                                            will always be used, but
  *                                            please set #U_LOCATION_TYPE_GNSS
@@ -401,11 +400,7 @@ typedef enum {
  *                                in which case location establishment will
  *                                stop when #U_LOCATION_TIMEOUT_SECONDS have
  *                                elapsed.  The single int32_t parameter is
- *                                the device handle, but note that if
- *                                pLocationAssist->networkHandleAssist is
- *                                set then the device handle may be that
- *                                of the assisting device, depending on
- *                                what stage location establishment is at.
+ *                                the device handle.
  * @return                        zero on success or negative error code
  *                                on failure.
  */
@@ -416,7 +411,7 @@ int32_t uLocationGet(uDeviceHandle_t devHandle, uLocationType_t type,
                      bool (*pKeepGoingCallback) (uDeviceHandle_t));
 
 /** Get the current location, non-blocking version.  uNetworkInterfaceUp()
- * (see the network API) must have been called on the given networkHandle
+ * (see the network API) must have been called on the given device handle
  * for this function to work.  This is a one-shot establishment:
  * once pCallback has been called it is over, you must call this
  * function again to start a new location establishment attempt.  If you
@@ -483,7 +478,7 @@ int32_t uLocationGetStart(uDeviceHandle_t devHandle, uLocationType_t type,
 
 /** Get the current location to a callback, continuously, until
  * told to stop.  uNetworkInterfaceUp() (see the network API) must
- * have been called on the given devHandle for this function to
+ * have been called on the given device handle for this function to
  * work.
  *
  * Note that if you have a GNSS chip inside your cellular module
@@ -518,7 +513,7 @@ int32_t uLocationGetStart(uDeviceHandle_t devHandle, uLocationType_t type,
  * @param desiredRateMs           the desired position-establishment rate
  *                                in milliseconds; realistically you can only
  *                                set a value smaller than a few seconds
- *                                if you are using a GNSS networkHandle.
+ *                                if you are using a GNSS devHandle.
  *                                For Wifi-based position this value must
  *                                be greater than zero but is [currently]
  *                                otherwise ignored: position is established

gnss/api/u_gnss.h

@@ -120,14 +120,14 @@ int32_t uGnssAdd(uGnssModuleType_t moduleType,
  * #U_GNSS_TRANSPORT_VIRTUAL_SERIAL because the GNSS chip is inside or
  * connected via an intermediate (for example cellular) module then you
  * should call this function to let the GNSS instance know that there
- * is such an intermediate device.  This is because some procedures,
+ * is such an intermediate device.  This is required because some procedures,
  * e.g. powering the GNSS device on or off, need to be done differently
  * when there is an intermediate module.  You do NOT need to call this
  * function (it will return an error) if you are using
- * #U_GNSS_TRANSPORT_AT as the code will already know that there is an
- * intermediate module in that case; likewise, if you are using
- * #U_GNSS_TRANSPORT_VIRTUAL_SERIAL for another reason, no intermediate
- * module is involved, you do not need to call this function.
+ * #U_GNSS_TRANSPORT_AT, as the code will already know that there is an
+ * intermediate module in that case.  Likewise, if you are using
+ * #U_GNSS_TRANSPORT_VIRTUAL_SERIAL for another reason and no
+ * intermediate module is involved, you do not need to call this function.
  *
  * @param gnssHandle          the handle of the GNSS instance.
  * @param intermediateHandle  the handle of the intermediate (e.g. cellular)

gnss/api/u_gnss_mga.h

@@ -397,7 +397,7 @@ typedef bool (uGnssMgaDatabaseCallback_t) (uDeviceHandle_t devHandle,
  * -------------------------------------------------------------- */
 
 /** Encode an AssistNow Online request body suitable for sending via
- * an HTTP GET request to a u-blox assistance server (e.g.
+ * an HTTP GET request to a u-blox assistance server (for example
  * online-live1.services.u-blox.com).  This does NOT send the HTTP
  * request: you must do that, e.g. using the uHttpClient API.  This
  * function is designed such that the buffer size may be determined
@@ -455,7 +455,7 @@ int32_t uGnssMgaOnlineRequestEncode(const uGnssMgaOnlineRequest_t *pRequest,
                                     char *pBuffer, size_t size);
 
 /** Encode an AssistNow Offline request body suitable for sending via an
- * HTTP GET request to a u-blox assistance server (e.g.
+ * HTTP GET request to a u-blox assistance server (for example
  * offline-live1.services.u-blox.com).  This does NOT send the HTTP
  * request: you must do that, e.g. using the uHttpClient API.  This
  * function is designed such that the buffer size may be determined
@@ -680,8 +680,8 @@ int32_t uGnssMgaSetAutonomous(uDeviceHandle_t gnssHandle, bool onNotOff);
  * followed by up to #U_GNSS_MGA_DBD_MESSAGE_PAYLOAD_LENGTH_MAX_BYTES
  * bytes of payload); pCallback will be called for each chunk returned.
  * pCallback must store the raw data (i.e. all up-to-166 bytes) in a
- * contigouous manner and return true on success, else return false
- * (in which case this function will return and the remaining chunks
+ * contigouous manner and return true on success, else false (in
+ * which case this function will return and the remaining chunks
  * will be ignored).  Database retrieval will time-out if the final ack
  * is not received within #U_GNSS_MGA_DATABASE_READ_TIMEOUT_MS.
  *

gnss/api/u_gnss_pwr.h

@@ -35,7 +35,7 @@
  * GNSS device for an overview of the terms used and a description
  * of the states involved; the state machine diagram is particularly
  * useful.  Note that power-saving is not supported on all GNSS devices
- * (e.g. ADR, FTS or HPG devices do not).
+ * (e.g. ADR, FTS and HPG devices do not).
  *
  * To define a few terms:
  *
@@ -320,7 +320,7 @@ int32_t uGnssPwrOffBackup(uDeviceHandle_t gnssHandle);
 int32_t uGnssPwrSetMode(uDeviceHandle_t gnssHandle, uGnssPwrSavingMode_t mode);
 
 /** Get the power-saving mode.  Note that power-saving is not
- * supported on all GNSS devices (e.g. ADR, FTS or HPG devices do not).
+ * supported on all GNSS devices (e.g. ADR, FTS and HPG devices do not).
  *
  * For M9 devices and later this is equivalent to getting key ID
  * #U_GNSS_CFG_VAL_KEY_ID_PM_OPERATEMODE_E1.

port/api/u_port_uart.h

@@ -73,7 +73,7 @@ extern "C" {
 
 #ifndef U_PORT_UART_PREFIX
 /** The UART prefix to use, on platforms where such a prefix
- * is employed (e.g. Linux).
+ * is employed (for example Linux).
  */
 # define U_PORT_UART_PREFIX "/dev/ttyUSB"
 #endif

port/platform/README.md

@@ -6,15 +6,19 @@ Also provided is a [static_size](static_size) "platform", which includes stubs f
 # Supported MCUs
 The MCUs supported by the platforms are as follows:
 
-- Espressif [ESP-IDF](esp-idf) and [Arduino-ESP32](arduino): ESP32.
+- Espressif [ESP-IDF](esp-idf): ESP32.
 - ST Microelectronics' [STM32Cube IDE](stm32cube): STM32F4.
-- Nordic [nRF5 SDK](nrf5sdk): NRF52.
 - [zephyr](zephyr): we test NRF52/NRF53, and also Linux/Posix for development purposes, but any MCU that is supported by Zephyr may work transparently.
 - not really an MCU but [windows](windows) is supported for development/test purposes.
 - [Linux](linux): not an MCU but native Linux is supported.
 
 In addition to the above, support is included for building certain frameworks as a `ubxlib` library under [PlatformIO](platformio). 
 
+The following platforms are currently supported but WILL BE DEPRECATED soon and will be REMOVED at the end of 2023:
+
+- [Arduino-ESP32](arduino): please build for Arduino through [PlatformIO](platformio) instead.
+- Nordic [nRF5 SDK](nrf5sdk) on NRF52: please use [zephyr](zephyr) instead.
+
 # Structure
 Each platform sub-directory includes the following items:
 

port/platform/arduino/README.md

@@ -1,4 +1,4 @@
-*** IMPORTANT: ONLY THE ESP32 CHIPSET IS SUPPORTED ON ARDUINO ***
+*** IMPORTANT: this platform is currently supported but WILL BE DEPRECATED soon and will be REMOVED at the end of 2023: please build for Arduino[ESP32] through [platformio](/port/platform/platformio) instead. ***
 
 # Preface
 This platform allows `ubxlib` to be called from within Arduino code.  It does not provide a C++ API into `ubxlib`, does not "Arduino-ise" the `ubxlib` architecture, i.e. `ubxlib` still requires the RTOS world of tasks, mutexes, queues etc., which is provided in this case by the underlying ESP-IDF SDK.