Skip to content
This repository has been archived by the owner on Nov 11, 2024. It is now read-only.

Commit

Permalink
uGnssAdd() change only: rationalise transport type enum. (#673)
Browse files Browse the repository at this point in the history 
*** THIS CHANGE ONLY AFFECTS YOU IF YOUR APPLICATION CALLS uGnssAdd(), OTHERWISE IT CAN BE IGNORED ***

The transport type enum used with uGnssAdd() is reduced to simply select UART, AT or I2C transport; the "UBX-only" version, in which NMEA messages will be filtered out, is deprecated and will, at some point in the future, be removed.  If you call uGnssAdd() directly and you wish to filter out NMEA messages you may do so by calling uGnssCfgSetProtocolOut() after you have powered the GNSS chip up; this is already done *automatically* for you if you are using the uDevice API, depending on the state of the includeNmea flag in the uDeviceCfgGnss_t structure passed to uDeviceOpen().  In other words if you are opening a GNSS device by calling uDeviceOpen() this commit does not affect you.

So, if you are calling uGnssAdd() directly, rather than using the uDevice API, your enum usage should change as follows:

U_GNSS_TRANSPORT_NMEA_UART   -> U_GNSS_TRANSPORT_UART
U_GNSS_TRANSPORT_NMEA_I2C    -> U_GNSS_TRANSPORT_I2C
U_GNSS_TRANSPORT_UBX_AT      -> U_GNSS_TRANSPORT_AT
U_GNSS_TRANSPORT_UBX_UART    -> U_GNSS_TRANSPORT_UART
U_GNSS_TRANSPORT_UBX_I2C     -> U_GNSS_TRANSPORT_I2C
  • Loading branch information
@RobMeades
RobMeades authored Aug 27, 2022
1 parent 834f498 commit f107a1c
Show file tree
Hide file tree
Showing 19 changed files with 186 additions and 180 deletions.
35 changes: 18 additions & 17 deletions common/device/src/u_device_private_gnss.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@
#include "u_gnss_type.h"
#include "u_gnss.h"
#include "u_gnss_pwr.h"
#include "u_gnss_cfg.h" // For uGnssCfgSetProtocolOut()

#include "u_device_private.h"
#include "u_device_shared_gnss.h"
Expand Down Expand Up @@ -101,35 +102,29 @@ static int32_t addDevice(int32_t transportHandle,
const uDeviceCfgGnss_t *pCfgGnss,
uDeviceHandle_t *pDeviceHandle)
{
int32_t errorCodeOrHandle = (int32_t) U_ERROR_COMMON_NO_MEMORY;
int32_t errorCode = (int32_t) U_ERROR_COMMON_NO_MEMORY;
uGnssTransportHandle_t gnssTransportHandle;
uGnssTransportType_t gnssTransportType = U_GNSS_TRANSPORT_UBX_UART;
uGnssTransportType_t gnssTransportType = U_GNSS_TRANSPORT_UART;
uDeviceGnssInstance_t *pContext;

// Populate gnssTransportHandle/gnssTransportType
if (transportType == U_DEVICE_TRANSPORT_TYPE_I2C) {
gnssTransportHandle.i2c = transportHandle;
gnssTransportType = U_GNSS_TRANSPORT_UBX_I2C;
if (pCfgGnss->includeNmea) {
gnssTransportType = U_GNSS_TRANSPORT_NMEA_I2C;
}
gnssTransportType = U_GNSS_TRANSPORT_I2C;
} else {
gnssTransportHandle.uart = transportHandle;
if (pCfgGnss->includeNmea) {
gnssTransportType = U_GNSS_TRANSPORT_NMEA_UART;
}
}

pContext = (uDeviceGnssInstance_t *) malloc(sizeof(uDeviceGnssInstance_t));
if (pContext != NULL) {
pContext->transportHandle = transportHandle;
pContext->transportType = transportType;
// Add the GNSS instance, which actually creates pDeviceHandle
errorCodeOrHandle = uGnssAdd((uGnssModuleType_t) pCfgGnss->moduleType,
gnssTransportType, gnssTransportHandle,
pCfgGnss->pinEnablePower, false,
pDeviceHandle);
if (errorCodeOrHandle == 0) {
errorCode = uGnssAdd((uGnssModuleType_t) pCfgGnss->moduleType,
gnssTransportType, gnssTransportHandle,
pCfgGnss->pinEnablePower, false,
pDeviceHandle);
if (errorCode == 0) {
if (pCfgGnss->i2cAddress > 0) {
uGnssSetI2cAddress(*pDeviceHandle, pCfgGnss->i2cAddress);
}
Expand All @@ -142,8 +137,14 @@ static int32_t addDevice(int32_t transportHandle,
// Attach the context
U_DEVICE_INSTANCE(*pDeviceHandle)->pContext = pContext;
// Power on the GNSS chip
errorCodeOrHandle = uGnssPwrOn(*pDeviceHandle);
if (errorCodeOrHandle != 0) {
errorCode = uGnssPwrOn(*pDeviceHandle);
if (errorCode == 0) {
if (!pCfgGnss->includeNmea) {
// Not checking for errors here, this is "best effort"
uGnssCfgSetProtocolOut(*pDeviceHandle,
U_GNSS_PROTOCOL_NMEA, false);
}
} else {
// If we failed to power on, clean up
removeDevice(*pDeviceHandle, false);
}
Expand All @@ -152,7 +153,7 @@ static int32_t addDevice(int32_t transportHandle,
}
}

return errorCodeOrHandle;
return errorCode;
}

/* ----------------------------------------------------------------
Expand Down
8 changes: 4 additions & 4 deletions common/location/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,11 @@ int app_start() {
.deviceCfg = {
.cfgGnss = {
.moduleType = U_CFG_TEST_GNSS_MODULE_TYPE,
.transportType = U_GNSS_TRANSPORT_UBX_UART,
.transportType = U_GNSS_TRANSPORT_UART,
.pinGnssEnablePower = U_CFG_APP_PIN_GNSS_ENABLE_POWER,
.devHandleAt = NULL, // Only relevant for transport U_GNSS_TRANSPORT_UBX_AT
.gnssAtPinPwr = -1, // Only relevant for transport U_GNSS_TRANSPORT_UBX_AT
.gnssAtPinDataReady = -1 // Only relevant for transport U_GNSS_TRANSPORT_UBX_AT
.devHandleAt = NULL, // Only relevant for transport U_GNSS_TRANSPORT_AT
.gnssAtPinPwr = -1, // Only relevant for transport U_GNSS_TRANSPORT_AT
.gnssAtPinDataReady = -1 // Only relevant for transport U_GNSS_TRANSPORT_AT
},
},
.transportType = U_DEVICE_TRANSPORT_TYPE_UART,
Expand Down
2 changes: 1 addition & 1 deletion gnss/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ int app_start() {
// the pin that enables power to the GNSS module; use
// -1 if there is no such pin.
uGnssAdd(U_GNSS_MODULE_TYPE_M8,
U_GNSS_TRANSPORT_NMEA_UART, transportHandle,
U_GNSS_TRANSPORT_UART, transportHandle,
U_CFG_APP_PIN_GNSS_ENABLE_POWER, false,
&gnssHandle);
Expand Down
4 changes: 2 additions & 2 deletions gnss/api/u_gnss_pwr.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,8 +112,8 @@ extern "C" {
* -------------------------------------------------------------- */

/** Power a GNSS chip on. If the transport type for the given GNSS
* instance is #U_GNSS_TRANSPORT_UBX_AT then you must have powered
* the associated cellular module up (e.g. with a call to uDeviceOpen()
* instance is #U_GNSS_TRANSPORT_AT then you must have powered
* the associated [cellular] module up (e.g. with a call to uDeviceOpen()
* or uCellPwrOn()) before calling this function. Also powering up
* a GNSS module which is attached via a cellular module will "claim"
* the GNSS module for this GNSS interface and so if you use the cellLoc
Expand Down
51 changes: 34 additions & 17 deletions gnss/api/u_gnss_type.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,31 +108,48 @@
// Suppress not used within defaulted switch
typedef enum {
U_GNSS_TRANSPORT_NONE,
U_GNSS_TRANSPORT_UBX_UART, /**< the transport handle should be a UART handle
over which ubx commands will be transferred;
NMEA will be switched off. */
U_GNSS_TRANSPORT_UBX_AT, /**< the transport handle should be an AT client
handle over which ubx commands will be
transferred. */
U_GNSS_TRANSPORT_NMEA_UART, /**< the transport handle should be a UART handle
over which NMEA commands may be received;
ubx commands will still be used by this code. */
U_GNSS_TRANSPORT_UBX_I2C, /**< the transport handle should be an I2C handle
U_GNSS_TRANSPORT_UART, /**< the transport handle should be a UART handle. */
U_GNSS_TRANSPORT_AT, /**< the transport handle should be an AT client
handle; currently only ubx-format messages may
be received when this transport type is in use. */
U_GNSS_TRANSPORT_I2C, /**< the transport handle should be an I2C handle. */
U_GNSS_TRANSPORT_UBX_UART, /**< \deprecated the transport handle should be a UART handle
over which ubx commands will be transferred;
NMEA will be switched off. */
U_GNSS_TRANSPORT_NMEA_I2C, /**< the transport handle should be an I2C handle
over which NMEA commands may be received;
ubx commands will still be used by this code. */
NMEA will be switched off; THIS IS DEPRECATED,
PLEASE USE #U_GNSS_TRANSPORT_UART instead
and use uGnssCfgSetProtocolOut() to switch
off NMEA message output if required. */
U_GNSS_TRANSPORT_UBX_I2C, /**< \deprecated the transport handle should be an I2C handle
over which ubx commands will be transferred;
NMEA will be switched off; THIS IS DEPRECATED,
PLEASE USE #U_GNSS_TRANSPORT_I2C instead and
use uGnssCfgSetProtocolOut() to switch off NMEA
message output if required. */
U_GNSS_TRANSPORT_MAX_NUM_WITH_UBX,
U_GNSS_TRANSPORT_UBX_AT = U_GNSS_TRANSPORT_AT, /**< \deprecated the transport handle should be an AT client
handle over which ubx commands will be
transferred; THIS IS DEPRECATED, PLEASE
USE #U_GNSS_TRANSPORT_AT instead. */
U_GNSS_TRANSPORT_NMEA_UART = U_GNSS_TRANSPORT_UART, /**< \deprecated the transport handle should be a UART handle
over which NMEA commands may be received;
ubx commands will still be used by this code.
THIS IS DEPRECATED, PLEASE USE
#U_GNSS_TRANSPORT_UART. */
U_GNSS_TRANSPORT_NMEA_I2C = U_GNSS_TRANSPORT_I2C, /**< \deprecated the transport handle should be an I2C handle
over which NMEA commands may be received;
ubx commands will still be used by this code.
THIS IS DEPRECATED, PLEASE USE
#U_GNSS_TRANSPORT_I2C. */
U_GNSS_TRANSPORT_MAX_NUM
} uGnssTransportType_t;

/** The handle for the transport with types implied by
* uGnssTransportType_t.
*/
typedef union {
void *pAt;
int32_t uart;
int32_t i2c;
void *pAt; /**< for transport type #U_GNSS_TRANSPORT_AT. */
int32_t uart; /**< for transport type #U_GNSS_TRANSPORT_UART. */
int32_t i2c; /**< for transport type #U_GNSS_TRANSPORT_I2C. */
} uGnssTransportHandle_t;

/** The protocol types for exchanges with a GNSS chip,
Expand Down
9 changes: 4 additions & 5 deletions gnss/api/u_gnss_util.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,12 +68,11 @@ extern "C" {
* is just the stream of output from the GNSS chip that came after
* the sent message. It is up to you to pick the exact response
* message out of the stream and parse it; if you are only using ubx
* format messages you may prefer to set the transport type to
* #U_GNSS_TRANSPORT_UBX_UART or #U_GNSS_TRANSPORT_UBX_I2C as
* appropriate to avoid NMEA messages getting in the way.
* format messages you may like to call uGnssCfgSetProtocolOut() to
* filter out NMEA messages.
*
* IMPORTANT: when the GNSS chip is connected via an intermediate
* [e.g. cellular] module (i.e. you are using #U_GNSS_TRANSPORT_UBX_AT)
* [e.g. cellular] module (i.e. you are using #U_GNSS_TRANSPORT_AT)
* then responses will only be returned by this function if UBX FORMAT
* is used; that is why this function has "ubx" in the name. However,
* the message contents are not touched by this code and hence could
Expand All @@ -82,7 +81,7 @@ extern "C" {
* last two bytes of the message with a ubx message checksum.
* Hence, you _can_ send a non-ubx-format message transparently
* to the GNSS chip with this function when using
* #U_GNSS_TRANSPORT_UBX_AT but be sure to add two dummy bytes
* #U_GNSS_TRANSPORT_AT but be sure to add two dummy bytes
* to the outgoing message buffer.
*
* It is planned, in future, to make transport via an intermediate
Expand Down
30 changes: 15 additions & 15 deletions gnss/src/u_gnss.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,11 +68,11 @@
//lint -esym(752, gpTransportTypeText) Suppress not referenced, which
// it won't be if diagnostic prints are compiled out
static const char *const gpTransportTypeText[] = {"None", // U_GNSS_TRANSPORT_NONE
"UART", // U_GNSS_TRANSPORT_UART
"AT", // U_GNSS_TRANSPORT_AT
"I2C", // U_GNSS_TRANSPORT_I2C
"ubx UART", // U_GNSS_TRANSPORT_UBX_UART
"ubx AT", // U_GNSS_TRANSPORT_UBX_AT
"NMEA UART", // U_GNSS_TRANSPORT_NMEA_UART
"ubx I2C", // U_GNSS_TRANSPORT_UBX_I2C
"NMEA I2C" // U_GNSS_TRANSPORT_NMEA_I2C
"ubx I2C" // U_GNSS_TRANSPORT_UBX_I2C
};

/* ----------------------------------------------------------------
Expand All @@ -92,17 +92,17 @@ static uGnssPrivateInstance_t *pGetGnssInstanceTransportHandle(uGnssTransportTyp
while ((pInstance != NULL) && !match) {
if (pInstance->transportType == transportType) {
switch (transportType) {
case U_GNSS_TRANSPORT_UBX_UART:
case U_GNSS_TRANSPORT_UART:
//lint -fallthrough
case U_GNSS_TRANSPORT_NMEA_UART:
case U_GNSS_TRANSPORT_UBX_UART:
match = (pInstance->transportHandle.uart == transportHandle.uart);
break;
case U_GNSS_TRANSPORT_UBX_AT:
case U_GNSS_TRANSPORT_AT:
match = (pInstance->transportHandle.pAt == transportHandle.pAt);
break;
case U_GNSS_TRANSPORT_UBX_I2C:
case U_GNSS_TRANSPORT_I2C:
//lint -fallthrough
case U_GNSS_TRANSPORT_NMEA_I2C:
case U_GNSS_TRANSPORT_UBX_I2C:
match = (pInstance->transportHandle.i2c == transportHandle.i2c);
break;
default:
Expand Down Expand Up @@ -254,9 +254,9 @@ int32_t uGnssAdd(uGnssModuleType_t moduleType,
errorCode = (int32_t) U_ERROR_COMMON_INVALID_PARAMETER;
if (((size_t) moduleType < gUGnssPrivateModuleListSize) &&
((transportType > U_GNSS_TRANSPORT_NONE) &&
(transportType < U_GNSS_TRANSPORT_MAX_NUM)) &&
((transportType == U_GNSS_TRANSPORT_UBX_I2C) ||
(transportType == U_GNSS_TRANSPORT_NMEA_I2C) ||
(transportType < U_GNSS_TRANSPORT_MAX_NUM_WITH_UBX)) &&
((transportType == U_GNSS_TRANSPORT_I2C) ||
(transportType == U_GNSS_TRANSPORT_UBX_I2C) ||
(pGetGnssInstanceTransportHandle(transportType, transportHandle) == NULL))) {
errorCode = (int32_t) U_ERROR_COMMON_NO_MEMORY;
// Allocate memory for the instance
Expand Down Expand Up @@ -284,8 +284,8 @@ int32_t uGnssAdd(uGnssModuleType_t moduleType,
pInstance->atModulePinPwr = -1;
pInstance->atModulePinDataReady = -1;
pInstance->portNumber = 0; // This is the I2C port number inside the GNSS chip
if ((transportType == U_GNSS_TRANSPORT_UBX_UART) ||
(transportType == U_GNSS_TRANSPORT_NMEA_UART)) {
if ((transportType == U_GNSS_TRANSPORT_UART) ||
(transportType == U_GNSS_TRANSPORT_UBX_UART)) {
pInstance->portNumber = 1; // This is the UART port number inside the GNSS chip
}
#ifdef U_CFG_GNSS_PORT_NUMBER
Expand Down Expand Up @@ -342,7 +342,7 @@ int32_t uGnssAdd(uGnssModuleType_t moduleType,
}

if ((errorCode == 0) && (platformError == 0)) {
if (pInstance->transportType != U_GNSS_TRANSPORT_UBX_AT) {
if (pInstance->transportType != U_GNSS_TRANSPORT_AT) {
errorCode = (int32_t) U_ERROR_COMMON_NO_MEMORY;
// Provided we're not on AT transport, i.e. we're on
// a streaming transport, then set up the buffer into
Expand Down
6 changes: 3 additions & 3 deletions gnss/src/u_gnss_pos.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -306,7 +306,7 @@ int32_t uGnssPosGet(uDeviceHandle_t gnssHandle,
pInstance = pUGnssPrivateGetInstance(gnssHandle);
if (pInstance != NULL) {
#ifdef U_CFG_SARA_R5_M8_WORKAROUND
if (pInstance->transportType == U_GNSS_TRANSPORT_UBX_AT) {
if (pInstance->transportType == U_GNSS_TRANSPORT_AT) {
// Temporary change: on prototype versions of the
// SARA-R10M8S module (production week (printed on the
// module label, upper right) earlier than 20/27)
Expand Down Expand Up @@ -388,7 +388,7 @@ int32_t uGnssPosGetStart(uDeviceHandle_t gnssHandle,
pParameters = (uGnssPosGetTaskParameters_t *) malloc(sizeof(*pParameters));
if (pParameters != NULL) {
#ifdef U_CFG_SARA_R5_M8_WORKAROUND
if (pInstance->transportType == U_GNSS_TRANSPORT_UBX_AT) {
if (pInstance->transportType == U_GNSS_TRANSPORT_AT) {
// Temporary change: on prototype versions of the
// SARA-R10M8S module (production week (printed on the
// module label, upper right) earlier than 20/27)
Expand Down Expand Up @@ -501,7 +501,7 @@ int32_t uGnssPosGetRrlp(uDeviceHandle_t gnssHandle, char *pBuffer,
(sizeBytes >= U_UBX_PROTOCOL_OVERHEAD_LENGTH_BYTES)) {

#ifdef U_CFG_SARA_R5_M8_WORKAROUND
if (pInstance->transportType == U_GNSS_TRANSPORT_UBX_AT) {
if (pInstance->transportType == U_GNSS_TRANSPORT_AT) {
// Temporary change: on prototype versions of the
// SARA-R10M8S module (production week (printed on the
// module label, upper right) earlier than 20/27)
Expand Down
Loading

0 comments on commit f107a1c

Please sign in to comment.