Documentation change only: better advice on use of M10 in LENA-R8xxxM10.

The LENA-R8xxxM10 cellular module does not support access to the built-in M10 chip via CMUX, and access to the GNSS chip via ye olde AT+UGUBX mechanism, while possible, has limitations since there can be message collisions with the UPOS entity inside the cellular module [which cannot be stopped from talking to the GNSS chip if _it_ has switched it on] at the same time, leading to communications failures.  Hence it is advisable to use the separate, dedicated, TXD_GNSS/RXD_GNSS pins that the LENA-R8 module offers to access the internal GNSS chip and treat the M10 as a standalone GNSS device from a ubxlib perspective.

Advice is added to the location API and the examples concerning this.

Our apologies to mos216 for not adding this advice earlier.

Author: RobMeades

common/location/api/u_location.h

@@ -340,6 +340,23 @@ typedef enum {
  * force use of AT commands, rather than the GNSS multiplexer channel, to
  * obtain position.
  *
+ * Note: if you would like to use the M10 device inside a LENA-R8xxxM10
+ * module, LENA-R8 does NOT support communication with that device via
+ * CMUX, which all of the APIs here will use by default.  You _may_ still
+ * use the APIs here if you define U_NETWORK_GNSS_CFG_CELL_USE_AT_ONLY when
+ * you build ubxlib, forcing the ubxlib code to use the more clunky, polling,
+ * AT+UGUBX mechanism to exchange messages with the GNSS chip, however
+ * continuous location (i.e. any API with "Continuous" in the name) is not
+ * possible via that polling mechanism and communication attempts may also
+ * occasionally fail, particularly soon after power-on of the GNSS chip,
+ * as responses from the GNSS chip to messages sent by the UPOS software
+ * entity of the LENA-R8 cellular chip, which cannot be stopped, may end
+ * up replacing the wanted reply.  Hence, for LENA-R8, it is advisable to
+ * power the internal GNSS chip from VCC_GNSS and connect a seperate UART from
+ * your MCU to the TXD_GNSS/RXD_GNSS pins offered by the LENA-R8 module;
+ * then, from a ubxlib perspective, you can treat the GNSS chip inside
+ * LENA-R8 as a standalone GNSS device.
+ *
  * @param devHandle               the device handle to use.
  * @param type                    the type of location fix to perform;
  *                                how this can be used depends upon the
@@ -444,6 +461,23 @@ int32_t uLocationGet(uDeviceHandle_t devHandle, uLocationType_t type,
  * force use of AT commands, rather than the GNSS multiplexer channel, to
  * obtain position.
  *
+ * Note: if you would like to use the M10 device inside a LENA-R8xxxM10
+ * module, LENA-R8 does NOT support communication with that device via
+ * CMUX, which all of the APIs here will use by default.  You _may_ still
+ * use the APIs here if you define U_NETWORK_GNSS_CFG_CELL_USE_AT_ONLY when
+ * you build ubxlib, forcing the ubxlib code to use the more clunky, polling,
+ * AT+UGUBX mechanism to exchange messages with the GNSS chip, however
+ * continuous location (i.e. any API with "Continuous" in the name) is not
+ * possible via that polling mechanism and communication attempts may also
+ * occasionally fail, particularly soon after power-on of the GNSS chip,
+ * as responses from the GNSS chip to messages sent by the UPOS software
+ * entity of the LENA-R8 cellular chip, which cannot be stopped, may end
+ * up replacing the wanted reply.  Hence, for LENA-R8, it is advisable to
+ * power the internal GNSS chip from VCC_GNSS and connect a seperate UART from
+ * your MCU to the TXD_GNSS/RXD_GNSS pins offered by the LENA-R8 module;
+ * then, from a ubxlib perspective, you can treat the GNSS chip inside
+ * LENA-R8 as a standalone GNSS device.
+ *
  * #U_LOCATION_TYPE_CLOUD_CLOUD_LOCATE is not currently supported by
  * this function.
  *
@@ -513,6 +547,9 @@ int32_t uLocationGetStart(uDeviceHandle_t devHandle, uLocationType_t type,
  * be unresponsive.  For that case, please call this function once at
  * startup, only calling uLocationGetStop() when you are shutting down.
  *
+ * Note: this API is NOT supported for the M10 GNSS device inside a
+ * LENA-R8xxxM10 module.
+ *
  * If you are requesting #U_LOCATION_TYPE_GNSS at a high rate (e.g. faster than
  * once per second) then, since this code only uses UBX messages, it will
  * switch off NMEA output from the GNSS chip in order to ensure the desired

example/location/README.md

@@ -7,8 +7,6 @@ These examples demonstrate how to establish location in three different configur
 - as above but continuously to a callback ([main_loc_gnss_cell_continuous.c](main_loc_gnss_cell_continuous.c)),
 - using cloud services such as Cell Locate via a cellular \[and in future Wi-Fi\] module ([main_loc_cell_locate.c](main_loc_cell_locate.c) and [main_loc_gnss_cloud_locate.c](main_loc_gnss_cloud_locate.c)); the latter Cloud Locate service is focussed on applications where the cloud needs to know the position of the device but the device itself does not.
 
-IMPORTANT: there will likely be modifications to this API as we introduce more location-type services, beware!
-
 # Usage
 To build and run these examples on a supported platform you need to travel down into the [port/platform](/port/platform)`/<platform>/mcu/<mcu>` directory of your choice and find the `runner` build.  The instructions there will tell you how to set/override \#defines.  The following \#defines are relevant:
 

example/location/main_loc_gnss_cell.c

@@ -19,6 +19,23 @@
  * a location fix, i.e. this example ONLY applies if your GNSS module is
  * attached to the cellular module and NOT to this MCU.
  *
+ * Note: if you would like to use the M10 device inside a LENA-R8xxxM10
+ * module, LENA-R8 does NOT support communication with that device via
+ * CMUX, which the location API will use by default.  You _may_ still
+ * use this example if you define U_NETWORK_GNSS_CFG_CELL_USE_AT_ONLY
+ * when you build ubxlib, forcing the ubxlib code to use the more clunky,
+ * polling, AT+UGUBX mechanism to exchange messages with the GNSS chip,
+ * however communication attempts may occasionally fail, particularly soon
+ * after power-on of the GNSS chip, as responses from the GNSS chip to
+ * messages sent by the UPOS software entity of the LENA-R8 cellular chip,
+ * which cannot be stopped, may end up replacing the wanted reply.  Hence,
+ * for LENA-R8, it is advisable to power the internal GNSS chip from VCC_GNSS
+ * and connect a seperate UART from your MCU to the TXD_GNSS/RXD_GNSS pins
+ * offered by the LENA-R8 module; then, from a ubxlib perspective, you can
+ * treat the GNSS chip inside LENA-R8 as a standalone GNSS device and
+ * follow the main_loc_gnss.c and main_loc_gnss_continuous.c examples
+ * instead.
+ *
  * The choice of module and the choice of platform on which this
  * code runs is made at build time, see the README.md for
  * instructions.

example/location/main_loc_gnss_cell_continuous.c

@@ -19,6 +19,10 @@
  * a location fix continuously, i.e. this example ONLY applies if your
  * GNSS module is attached to the cellular module and NOT to this MCU.
  *
+ * Note that this example will NOT work for LENA-R8xxxM10 since LENA-R8
+ * does not support CMUX access to the built-in GNSS chip and that is
+ * required for continuous location.
+ *
  * The choice of module and the choice of platform on which this
  * code runs is made at build time, see the README.md for
  * instructions.