Skip to content

Commit

Permalink
New device and network APIs: general documentation update.
Browse files Browse the repository at this point in the history 
Eradicate all mentions of the old uNetworkInit()/uNetworkAdd()/uNetworkUp()/uNetworkDown()/uNetworkRemove()/uNetworkDeinit() APIs, replacing them with the appropriate new API.
  • Loading branch information
@RobMeades
RobMeades committed May 31, 2022
1 parent 48722f2 commit c5806ec
Show file tree
Hide file tree
Showing 9 changed files with 73 additions and 74 deletions.
2 changes: 1 addition & 1 deletion cell/api/u_cell_sec.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -482,7 +482,7 @@ int32_t uCellSecPskGenerate(uDeviceHandle_t cellHandle,
* once every 24 hours) the trigger request may return an error.
*
* @param cellHandle the handle of the instance to be used, e.g.
* as returned by uNetworkAdd().
* obtained through uDeviceOpen().
* @return zero on success else negative error code.
*/
int32_t uCellSecHeartbeatTrigger(uDeviceHandle_t cellHandle);
Expand Down
14 changes: 7 additions & 7 deletions common/location/api/u_location.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
* 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
* uNetworkDeinit()) while an asynchronous location request is
* uDeviceDeinit()) while an asynchronous location request is
* outstanding.
*/

Expand Down Expand Up @@ -250,9 +250,9 @@ typedef enum {
* -------------------------------------------------------------- */

/** Get the current location, returning on success or when
* pKeepGoingCallback returns false. uNetworkUp() (see the network
* API) must have been called on the given networkHandle for this
* function to work.
* pKeepGoingCallback returns false. uNetworkInterfaceUp() (see the
* network API) must have been called on the given networkHandle 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
* location call on the cell network will use that GNSS chip, there
Expand Down Expand Up @@ -348,9 +348,9 @@ int32_t uLocationGet(uDeviceHandle_t devHandle, uLocationType_t type,
uLocation_t *pLocation,
bool (*pKeepGoingCallback) (uDeviceHandle_t));

/** Get the current location, non-blocking version. uNetworkUp() (see
* the network API) must have been called on the given networkHandle for
* this function to work.
/** Get the current location, non-blocking version. uNetworkInterfaceUp()
* (see the network API) must have been called on the given networkHandle
* 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
* location call on the cell network will use that GNSS chip, there is
Expand Down
2 changes: 1 addition & 1 deletion common/mqtt_client/api/u_mqtt_client.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ typedef struct {
* to put them back again.
*
* @param devHandle the device handle to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
* @param[in] pSecurityTlsSettings a pointer to the security settings to
* be applied, NULL for no security.
* If this is non-NULL, don't forget to
Expand Down
55 changes: 26 additions & 29 deletions common/security/api/u_security.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ extern "C" {
/** Get whether a module supports u-blox security services or not.
*
* @param devHandle the handle of the instance to be used, e.g.
* as returned by uNetworkAdd().
* obtained using uDeviceOpen().
* @return true if the module supports u-blox security
* services else false.
*/
Expand All @@ -135,7 +135,7 @@ bool uSecurityIsSupported(uDeviceHandle_t devHandle);
* to uSecuritySealSet().
*
* @param devHandle the handle of the instance to be used, e.g.
* as returned by uNetworkAdd().
* obtained using uDeviceOpen().
* @return true if the module has been successfully
* boot-strapped with u-blox security services,
* else false.
Expand All @@ -149,8 +149,7 @@ bool uSecurityIsBootstrapped(uDeviceHandle_t devHandle);
* null-terminated string.
*
* @param devHandle the handle of the instance to
* be used, e.g. as returned by
* uNetworkAdd().
* be used, e.g. obtained using uDeviceOpen().
* @param pSerialNumber pointer to storage of at least
* U_SECURITY_SERIAL_NUMBER_MAX_LENGTH_BYTES
* where the serial number string will be
Expand All @@ -169,8 +168,7 @@ int32_t uSecurityGetSerialNumber(uDeviceHandle_t devHandle,
* the module are ready for use (i.e. if it returns non-negative).
*
* @param devHandle the handle of the instance to
* be used, e.g. as returned by
* uNetworkAdd().
* be used, e.g. obtained using uDeviceOpen().
* @param pRootOfTrustUid pointer to storage of at least
* U_SECURITY_ROOT_OF_TRUST_UID_LENGTH_BYTES
* where the root of trust UID will be placed,
Expand Down Expand Up @@ -209,7 +207,7 @@ int32_t uSecurityGetRootOfTrustUid(uDeviceHandle_t devHandle,
* hence it may be worth re-trying C2C pairing on failure.
*
* @param devHandle the handle of the instance to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
* @param pTESecret a pointer to the fixed-length 16 byte
* secret generated by this MCU (the
* "Terminal Equipment") to be used in the
Expand Down Expand Up @@ -252,7 +250,7 @@ int32_t uSecurityC2cPair(uDeviceHandle_t devHandle,
* on your UART port.
*
* @param devHandle the handle of the instance to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
* @param pTESecret a pointer to the fixed-length 16 byte
* secret key that was used during pairing;
* cannot be NULL.
Expand All @@ -275,7 +273,7 @@ int32_t uSecurityC2cOpen(uDeviceHandle_t devHandle,
* this function will do nothing and return success.
*
* @param devHandle the handle of the instance to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
* @return zero on success else negative error code.
*/
int32_t uSecurityC2cClose(uDeviceHandle_t devHandle);
Expand All @@ -286,15 +284,15 @@ int32_t uSecurityC2cClose(uDeviceHandle_t devHandle);

/** Request security sealing of a module. The module must have an
* active connection for the sealing process to succeed (e.g. by
* calling uNetworkUp() on the given handle). Sealing may take some
* time, hence pKeepGoingCallback is provided as a mean for the caller
* to stop waiting for the outcome. This function will return an error
* if the module is already security sealed; use uSecuritySealGet()
* to check whether this is the case.
* calling uNetworkInterfaceUp() on the given handle). Sealing may
* take some time, hence pKeepGoingCallback is provided as a mean for
* the caller to stop waiting for the outcome. This function will
* return an error if the module is already security sealed; use
* uSecuritySealGet() to check whether this is the case.
*
* @param devHandle the handle of the instance to
* be used, e.g. as returned by
* uNetworkAdd().
* be used, e.g. obtained using
* uDeviceOpen().
* @param pDeviceProfileUid the null-terminated device
* profile UID string provided by
* u-blox.
Expand Down Expand Up @@ -340,7 +338,7 @@ int32_t uSecuritySealSet(uDeviceHandle_t devHandle,
/** Get the security seal status of a module.
*
* @param devHandle the handle of the instance to be used, e.g.
* as returned by uNetworkAdd().
* obtained using uDeviceOpen().
* @return true if the module has been successfully
* security sealed, else false.
*/
Expand Down Expand Up @@ -376,8 +374,8 @@ bool uSecurityIsSealed(uDeviceHandle_t devHandle);
* called, otherwise it will return an error.
*
* @param devHandle the handle of the instance to
* be used, e.g. as returned by
* uNetworkAdd().
* be used, e.g. obtained using
* uDeviceOpen().
* @param pData a pointer to somewhere to store
* the certificate; use NULL to
* just get the size required without
Expand Down Expand Up @@ -419,8 +417,8 @@ int32_t uSecurityZtpGetDeviceCertificate(uDeviceHandle_t devHandle,
* called, otherwise it will return an error.
*
* @param devHandle the handle of the instance to
* be used, e.g. as returned by
* uNetworkAdd().
* be used, e.g. obtained using
* uDeviceOpen().
* @param pData a pointer to somewhere to store
* the key; use NULL to just get the size
* required without any actual data being
Expand Down Expand Up @@ -463,8 +461,8 @@ int32_t uSecurityZtpGetPrivateKey(uDeviceHandle_t devHandle,
* called, otherwise it will return an error.
*
* @param devHandle the handle of the instance to
* be used, e.g. as returned by
* uNetworkAdd().
* be used, e.g. obtained using
* uDeviceOpen().
* @param pData a pointer to somewhere to store
* the certificate authorities; use
* NULL to just get the size required
Expand Down Expand Up @@ -492,7 +490,7 @@ int32_t uSecurityZtpGetCertificateAuthorities(uDeviceHandle_t devHandle,
* setting the E2E encryption version.
*
* @param devHandle the handle of the instance to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
* @param version the version to use; 1 for version 1, etc.
* @return zero on success else negative error code.
*/
Expand All @@ -503,7 +501,7 @@ int32_t uSecurityE2eSetVersion(uDeviceHandle_t devHandle, int32_t version);
* E2E encryption version.
*
* @param devHandle the handle of the instance to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
* @return on success the E2E encryption version
* (1 for version 1, etc.), else negative
* error code.
Expand All @@ -518,7 +516,7 @@ int32_t uSecurityE2eGetVersion(uDeviceHandle_t devHandle);
* REST API.
*
* @param devHandle the handle of the instance to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
* @param pDataIn a pointer to dataSizeBytes of data to be
* encrypted, may be NULL, in which case this
* function does nothing.
Expand Down Expand Up @@ -555,8 +553,7 @@ int32_t uSecurityE2eEncrypt(uDeviceHandle_t devHandle,
* them into the security settings structure.
*
* @param devHandle the handle of the instance to
* be used, e.g. as returned by
* uNetworkAdd().
* be used, e.g. obtained using uDeviceOpen().
* @param pskSizeBytes the size of PSK to be generated: can be
* 16 bytes or 32 bytes.
* @param pPsk a pointer to storage for 16 or 32 bytes
Expand Down Expand Up @@ -589,7 +586,7 @@ int32_t uSecurityPskGenerate(uDeviceHandle_t devHandle,
* once every 24 hours) the trigger request may return an error.
*
* @param devHandle the handle of the instance to be used, e.g.
* as returned by uNetworkAdd().
* obtained using uDeviceOpen().
* @return zero on success else negative error code.
*/
int32_t uSecurityHeartbeatTrigger(uDeviceHandle_t devHandle);
Expand Down
12 changes: 6 additions & 6 deletions common/security/api/u_security_credential.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,7 @@ typedef struct {
* on the interface to the module.
*
* @param devHandle the handle of the instance to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
* @param type the type of credential to be stored.
* @param pName the null-terminated name for the
* X.509 certificate or security key, of
Expand Down Expand Up @@ -200,7 +200,7 @@ int32_t uSecurityCredentialStore(uDeviceHandle_t devHandle,
* The hash is that of the DER-format key as stored in the module.
*
* @param devHandle the handle of the instance to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
* @param type the type of credential, as was passed to
* uSecurityCredentialStore() when storing it.
* @param pName the null-terminated name for the
Expand Down Expand Up @@ -242,7 +242,7 @@ int32_t uSecurityCredentialGetHash(uDeviceHandle_t devHandle,
* uSecurityZtp*() APIs in u_security.h.
*
* @param devHandle the handle of the instance to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
* @param pCredential pointer to somewhere to store the result.
* @return the number of credentials in the list
* or negative error code.
Expand All @@ -268,7 +268,7 @@ int32_t uSecurityCredentialListFirst(uDeviceHandle_t devHandle,
* uSecurityZtp*() APIs in u_security.h.
*
* @param devHandle the handle of the instance to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
* @param pCredential pointer to somewhere to store the result.
* @return the number of entries remaining *after*
* this one has been read or negative error
Expand All @@ -282,14 +282,14 @@ int32_t uSecurityCredentialListNext(uDeviceHandle_t devHandle,
* iterate through the whole list with uSecurityCredentialListNext().
*
* @param devHandle the handle of the instance to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
*/
void uSecurityCredentialListLast(uDeviceHandle_t devHandle);

/** Remove the given X.509 certificate or security key from storage.
*
* @param devHandle the handle of the instance to be used,
* e.g. as returned by uNetworkAdd().
* e.g. obtained using uDeviceOpen().
* @param type the type of credential to be removed, as
* was passed to uSecurityCredentialStore()
* when storing it.
Expand Down
2 changes: 1 addition & 1 deletion common/security/api/u_security_tls.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -419,7 +419,7 @@ typedef struct uSecurityTlsContext_t {
*
* @param devHandle the handle of the device which the
* TLS security context is associated, e.g.
* as returned by uNetworkAdd().
* obtained using uDeviceOpen().
* @param pSettings a pointer to the TLS security settings
* to use. May be NULL in which case default
* settings are applied; consult the security
Expand Down
2 changes: 1 addition & 1 deletion common/sock/api/u_sock.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -363,7 +363,7 @@ typedef struct {
*
* @param devHandle the handle of the underlying network
* layer to use, usually established by
* a call to uNetworkAdd().
* a call to uDeviceOpen().
* @param type the type of socket to create.
* @param protocol the protocol that will run over the given
* socket.
Expand Down
2 changes: 1 addition & 1 deletion gnss/api/u_gnss_pwr.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ 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 uNetworkAdd()
* 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
56 changes: 29 additions & 27 deletions wifi/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,23 +25,10 @@ The [api](api) directory contains the files that define the Wi-Fi APIs, each API
HOWEVER for Wi-Fi connection and data transfer the recommendation is to use the [common/network](/common/network) API, along with the [common/sock](/common/sock) API. The handle returned by `uNetworkAdd()` can still be used with the `wifi` API for configuration etc. Please see the [socket example](/example/sockets) for details.

## Example
Below is a simple example that will setup a Wi-Fi connection using the [common/network](/common/network) API:
Below is a simple example that will setup a Wi-Fi connection using the [common/device](/common/device) and [common/network](/common/network) APIs:

```c
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>

#include "u_cfg_sw.h"
#include "u_cfg_os_platform_specific.h"

#include "u_port.h"
#include "u_port_debug.h"
#include "u_port_os.h"

#include "u_short_range_module_type.h"
#include "u_network.h"
#include "u_network_config_wifi.h"
#include <ubxlib.h>

#define VERIFY(cond, fail_msg) \
if (!(cond)) {\
Expand All @@ -58,33 +45,48 @@ int main(void)
{
uDeviceHandle_t devHandle = NULL;

static const uNetworkConfigurationWifi_t wifiConfig = {
static const uDeviceCfg_t gDeviceCfg = {
.deviceType = U_DEVICE_TYPE_SHORT_RANGE,
.deviceCfg = {
.cfgSho = {
.moduleType = U_SHORT_RANGE_MODULE_TYPE_NINA_W15
}
},
.transportType = U_DEVICE_TRANSPORT_TYPE_UART,
.transportCfg = {
.cfgUart = {
.uart = 1,
.baudRate = 115200,
.pinTxd = -1,
.pinRxd = -1,
.pinCts = -1,
.pinRts = -1
}
}
};

static const uNetworkCfgWifi_t gNetworkCfg = {
.type = U_NETWORK_TYPE_WIFI,
.module = U_SHORT_RANGE_MODULE_TYPE_NINA_W15,
.uart = 1,
.pinTxd = -1,
.pinRxd = -1,
.pinCts = -1,
.pinRts = -1,
.pSsid = "MySSID",
.authentication = 2 /* WPA/WPA2/WPA3 - see wifi/api/u_wifi.h */,
.pPassPhrase = "MyPassphrase"
};

VERIFY(uPortInit() == 0, "uPortInit failed\n");
VERIFY(uNetworkInit() == 0, "uNetworkInit failed\n");
VERIFY(uDeviceInit() == 0, "uDeviceInit failed\n");

VERIFY(uNetworkAdd(U_NETWORK_TYPE_WIFI, &wifiConfig, devHandle) == 0, "uNetworkAdd failed\n");
VERIFY(uDeviceOpen(&gDeviceCfg, &devHandle) == 0, "uDeviceOpen failed\n");
uPortLog("Bring up Wi-Fi\n");
VERIFY(uNetworkUp(devHandle) == 0, "uNetworkUp failed\n");
VERIFY(uNetworkInterfaceUp(devHandle, U_NETWORK_TYPE_WIFI, &gNetworkCfg) == 0, "uNetworkInterfaceUp failed\n");

uPortLog("Wi-Fi connected\n");
// Just sleep for 10 sec
uPortTaskBlock(10*1000);

// Cleanup
uNetworkDown(devHandle);
uNetworkDeinit();
uNetworkInterfaceDown(devHandle, U_NETWORK_TYPE_WIFI);
uDeviceClose(devHandle);
uDeviceDeinit();
uPortDeinit();

while(true);
Expand Down

0 comments on commit c5806ec

Please sign in to comment.