PDN

The PDN library can be used to manage Packet Data Protocol (PDP) contexts and PDN connections. It provides an API for the following purposes:

  • Creating and configuring PDP contexts

  • Receiving events pertaining to the PDN connections

  • Managing PDN connections

The library uses several AT commands, and it relies on the following two types of AT notifications to work:

  • Packet domain events notifications (+CGEV) - Subscribed by using the AT+CGEREP=1 command. See the AT+CGEREP set command section in the nRF9160 AT Commands Reference Guide or the same section in the nRF91x1 AT Commands Reference Guide, depending on the SiP you are using.

  • Notifications for unsolicited reporting of error codes sent by the network (+CNEC) - Subscribed by using the AT+CNEC=16 command. See the AT+CNEC set command section in the nRF9160 AT Commands Reference Guide or the same section in the nRF91x1 AT Commands Reference Guide, depending on the SiP you are using.

The PDN library automatically subscribes to the necessary AT notifications using Modem library callbacks. This includes automatically resubscribing to the notifications upon functional mode changes.

Note

The subscription to AT notifications is lost upon changing the modem functional mode to +CFUN=0. If the application subscribes to these notifications manually, it must also take care of resubscription.

Following are the AT commands that are used by the library:

  • AT%XNEWCID - To create a PDP context

  • AT+CGDCONT - To configure or destroy a PDP context

  • AT+CGACT - To activate or deactivate a PDN connection

  • AT%XGETPDNID- To retrieve the PDN ID for a given PDP context

  • AT+CGAUTH - To set the PDN connection authentication parameters

For more information about these commands, see Packet Domain AT commands in the nRF9160 AT Commands Reference Guide or the same section in the nRF91x1 AT Commands Reference Guide, depending on the SiP you are using.

The application can create PDP contexts by using the pdn_ctx_create() function, and a callback can be assigned to receive the events pertaining to the state and connectivity of the PDP contexts. The application can use the pdn_default_ctx_cb_reg() function to register an event handler for events pertaining the default PDP context, and the pdn_default_ctx_cb_dereg() to deregister it. The library stores 12 bytes of memory on the system heap for each PDP context created using pdn_ctx_create() and for each event handler for the default PDP context. The maximum number of PDP contexts that can be created is limited by the maximum number of PDP context supported by the nRF91 Series modem firmware and the amount of system heap memory available. The pdn_ctx_configure() function is used to configure a PDP context, which can be configured with a family, access point name, and optional authentication parameters. The pdn_activate() function activates a PDN connection for a PDP context. A PDN connection is identified by an ID as reported by AT%XGETPDNID, and it is distinct from the PDP context ID (CID). The modem creates a PDN connection for a PDP context as necessary. Multiple PDP contexts might share the same PDN connection if they are configured similarly.

Configuration

The PDN library overrides the default PDP context configuration automatically after the Modem library is initialized, if the CONFIG_PDN_DEFAULTS_OVERRIDE Kconfig option is set. The default PDP context configuration consists of the following parameters, each controlled with a Kconfig setting:

Note

The default PDP context configuration must be overridden before the device is registered with the network.

Limitations

You have to set the callback for the default PDP context before the device is registered to the network (CFUN=1) to receive the first activation event.

API documentation

Header file: include/modem/pdn.h
Source file: lib/pdn/pdn.c
group pdn

Typedefs

typedef void (*pdn_event_handler_t)(uint8_t cid, enum pdn_event event, int reason)

Event handler for PDN events. If assigned during PDP context creation, the event handler will receive status information relative to the Packet Data Network connection, as reported by the AT notifications +CNEC and +GGEV.

This handler is executed by the same context that dispatches AT notifications.

Param cid:

The PDP context ID.

Param event:

The event.

Param reason:

The ESM error reason, if available.

Enums

enum pdn_fam

PDN family.

Values:

enumerator PDN_FAM_IPV4

IPv4 family

enumerator PDN_FAM_IPV6

IPv6 family

enumerator PDN_FAM_IPV4V6

IPv4 and IPv6 family

enumerator PDN_FAM_NONIP

Non-IP family

enum pdn_event

PDN library event.

Values:

enumerator PDN_EVENT_CNEC_ESM

+CNEC ESM error code

enumerator PDN_EVENT_ACTIVATED

PDN connection activated

enumerator PDN_EVENT_DEACTIVATED

PDN connection deactivated

enumerator PDN_EVENT_IPV6_UP

PDN has IPv6 connectivity

enumerator PDN_EVENT_IPV6_DOWN

PDN has lost IPv6 connectivity

enumerator PDN_EVENT_NETWORK_DETACH

Network detached

enumerator PDN_EVENT_APN_RATE_CONTROL_ON

APN rate control is ON for given PDN

enumerator PDN_EVENT_APN_RATE_CONTROL_OFF

APN rate control is OFF for given PDN

enum pdn_auth

PDN authentication method.

Values:

enumerator PDN_AUTH_NONE

No authentication

enumerator PDN_AUTH_PAP

Password authentication protocol

enumerator PDN_AUTH_CHAP

Challenge handshake authentication protocol

Functions

int pdn_ctx_create(uint8_t *cid, pdn_event_handler_t cb)

Create a Packet Data Protocol (PDP) context.

If a callback is provided via the cb parameter, the library will generate events from the +CNEC and +GGEV AT notifications to report state of the Packet Data Network (PDN) connection.

Parameters:

  • cid – [out] The ID of the new PDP context.

  • cb – Optional event handler.

Returns:

int Zero on success or a negative errno otherwise.

int pdn_ctx_configure(uint8_t cid, const char *apn, enum pdn_fam family, struct pdn_pdp_opt *opts)

Configure a Packet Data Protocol context.

The PDN connection must be inactive when the PDP context is configured.

Parameters:

  • cid – The PDP context to configure.

  • apn – The Access Point Name to configure the PDP context with.

  • family – The family to configure the PDN context for.

  • opts – Optional additional configuration options.

Returns:

int Zero on success or a negative errno otherwise.

int pdn_ctx_auth_set(uint8_t cid, enum pdn_auth method, const char *user, const char *password)

Set PDN connection authentication parameters.

Parameters:

  • cid – The PDP context to set authentication parameters for.

  • method – The desired authentication method.

  • user – The username to use for authentication.

  • password – The password to use for authentication.

Returns:

int Zero on success or a negative errno otherwise.

int pdn_ctx_destroy(uint8_t cid)

Destroy a Packet Data Protocol context.

The PDN connection must be inactive when the PDP context is destroyed.

Parameters:

  • cid – The PDP context to destroy.

Returns:

int Zero on success or a negative errno otherwise.

int pdn_activate(uint8_t cid, int *esm, enum pdn_fam *family)

Activate a Packet Data Network (PDN) connection.

Parameters:

  • cid – The PDP context ID to activate a connection for.

  • esm – [out] If provided, the function will block to return the ESM error reason.

  • family – [out] If provided, the function will block to return PDN_FAM_IPV4 if only IPv4 is supported, or PDN_FAM_IPV6 if only IPv6 is supported. Otherwise, this value will remain unchanged.

Returns:

int Zero on success or a negative errno otherwise.

int pdn_deactivate(uint8_t cid)

Deactivate a Packet Data Network (PDN) connection.

Parameters:

  • cid – The PDP context ID.

Returns:

int Zero on success or a negative errno otherwise.

int pdn_id_get(uint8_t cid)

Retrieve the PDN ID for a given PDP Context.

The PDN ID can be used to route traffic through a Packet Data Network.

Parameters:

  • cid – The context ID of the PDN connection.

Returns:

int A non-negative PDN ID on success, or a negative errno otherwise.

int pdn_dynamic_params_get(uint8_t cid, struct in_addr *dns4_pri, struct in_addr *dns4_sec, unsigned int *ipv4_mtu)

Retrieve dynamic parameters of a given PDP context.

Parameters:

  • cid – The PDP context ID.

  • dns4_pri – [out] The address of the primary IPv4 DNS server. Optional, can be NULL.

  • dns4_sec – [out] The address of the secondary IPv4 DNS server. Optional, can be NULL.

  • ipv4_mtu – [out] The IPv4 MTU. Optional, can be NULL.

Returns:

Zero on success or an error code on failure.

int pdn_default_apn_get(char *buf, size_t len)

Retrieve the default Access Point Name (APN).

The default APN is the APN of the default PDP context (zero).

Parameters:

  • buf – [out] The buffer to copy the APN into.

  • len – The size of the output buffer.

Returns:

int Zero on success or a negative errno otherwise.

int pdn_default_ctx_cb_reg(pdn_event_handler_t cb)

Register a callback for events pertaining to the default PDP context (zero).

Parameters:

  • cb – The PDN event handler.

int pdn_default_ctx_cb_dereg(pdn_event_handler_t cb)

Deregister a callback for events pertaining to the default PDP context (zero).

Parameters:

  • cb – The PDN event handler.

struct pdn_pdp_opt
#include <pdn.h>

Additional PDP Context configuration options.

Public Members

uint8_t ip4_addr_alloc

IPv4 address allocation. 0 – IPv4 address via Non-access Stratum (NAS) signaling (default) 1 – IPv4 address via Dynamic Host Configuration Protocol (DHCP)

uint8_t nslpi

NAS Signalling Low Priority Indication. 0 – Use Non-access Stratum (NAS) Signalling Low Priority Indication (NSLPI) value from configuration (default) 1 – Use value “Not configured” for NAS Signalling Low Priority Indication.

uint8_t secure_pco

Protected transmission of Protocol Configuration Options (PCO). 0 – Protected transmission of PCO is not requested (default) 1 – Protected transmission of PCO is requested.