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 set command (AT+CGEREP=1)

  • Notifications for unsolicited reporting of error codes sent by the network (+CNEC) - Subscribed by using the AT+CNEC set command (AT+CNEC=16)

Note

The application must subscribe to the AT notifications for packet domain events and unsolicited reporting of error codes manually.

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.

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 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 during initialization (pdn_init()) if you have set the CONFIG_PDN_DEFAULTS_OVERRIDE Kconfig option. 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
enumerator PDN_FAM_IPV6
enumerator PDN_FAM_IPV4V6
enumerator PDN_FAM_NONIP
enum pdn_event

PDN library event.

Values:

enumerator PDN_EVENT_CNEC_ESM
enumerator PDN_EVENT_ACTIVATED

+CNEC ESM error code

enumerator PDN_EVENT_DEACTIVATED

PDN connection activated

enumerator PDN_EVENT_IPV6_UP

PDN connection deactivated

enumerator PDN_EVENT_IPV6_DOWN

PDN has IPv6 connectivity

enum pdn_auth

PDN authentication method.

Values:

enumerator PDN_AUTH_NONE
enumerator PDN_AUTH_PAP

No authentication

enumerator PDN_AUTH_CHAP

Password authentication protocol

Functions

int pdn_init(void)

Initialize the PDN library.

Returns

int Zero on success or a negative errno otherwise.

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_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_callback_set(pdn_event_handler_t cb)

Set 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.