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 PDP state and connectivity
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 for the functioning of the library.
Following are the AT commands that are used by the library:
AT%XNEWCID
- To create a PDP contextAT+CGDCONT
- To configure or destroy a PDP contextAT+CGACT
- To activate or deactivate a PDN connectionAT%XGETPDNID
- To retrieve the PDN ID for a given PDP contextAT+CGAUTH
- To set the PDN connection authentication parameters
For more information, 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.
The library requires the following Kconfig options to be set to y
:
Configuration¶
The default PDP context configuration consists of the following parameters:
Access point name
Family
Authentication method
Authentication credentials
The PDN library can override the default PDP context configuration by using the CONFIG_PDN_DEFAULTS_OVERRIDE
Kconfig option.
Limitations¶
The callback for the default PDP context must be set before the device is put to function mode 1 (CFUN=1) to receive the first activation event.
API documentation¶
include/modem/pdn.h
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.
- Parameters
cid – The PDP context ID.
event – The event.
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
¶
-
enumerator
-
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
-
enumerator
Functions
-
int
pdn_init
(void)¶ Initialize the PDN library.
This library depends on the AT command interface driver and AT command notification manager libraries, and they must be both initialized before initializing this 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)¶ 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.
- 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.
-
uint8_t
-
typedef void (*