Cellular Framework Example using Quectel CATM1 API

SF_CELLULAR Framework API on Quectel CATM1. More...

Functions
ssp_err_t	SF_CELLULAR_QCTLCATM1_Open (sf_cellular_ctrl_t *p_ctrl, sf_cellular_cfg_t const *const p_cfg)
	Initialize Cellular Quectel CATM1 Cellular driver. More...
ssp_err_t	SF_CELLULAR_QCTLCATM1_Close (sf_cellular_ctrl_t *const p_ctrl)
	Stop Cellular QuecTel CATM1 driver functionality. More...
ssp_err_t	SF_CELLULAR_QCTLCATM1_ProvisioningSet (sf_cellular_ctrl_t *const p_ctrl, sf_cellular_provisioning_t const *const p_cellular_provisioning)
	Sets the provisioning information. More...
ssp_err_t	SF_CELLULAR_QCTLCATM1_NetworkStatusGet (sf_cellular_ctrl_t *const p_ctrl, sf_cellular_network_status_t *p_network_status)
	Get Network Status information. More...
ssp_err_t	SF_CELLULAR_QCTLCATM1_InfoGet (sf_cellular_ctrl_t *const p_ctrl, sf_cellular_info_t *const p_cellular_info)
	Get Cellular module information. More...
ssp_err_t	SF_CELLULAR_QCTLCATM1_VersionGet (ssp_version_t *const p_version)
	Get driver version based on compile time macros. More...
ssp_err_t	SF_CELLULAR_QCTLCATM1_Reset (sf_cellular_ctrl_t *const p_ctrl, sf_cellular_reset_type_t reset_type)
	Reset the module. More...
ssp_err_t	sf_cellular_qctlcatm1_config_set (sf_cellular_ctrl_t *p_ctrl, sf_cellular_cfg_t const *p_cfg)
	Set Cellular device interface configuration. More...
ssp_err_t	sf_cellular_qctlcatm1_get_imsi (sf_cellular_instance_cfg_t *p_celr_instance, uint8_t *p_imsi)
	Read IMSI ID. More...

Detailed Description

SF_CELLULAR Framework API on Quectel CATM1.

Function Documentation

SF_CELLULAR_QCTLCATM1_Close()

ssp_err_t SF_CELLULAR_QCTLCATM1_Close

(

sf_cellular_ctrl_t *const

p_ctrl

)

Stop Cellular QuecTel CATM1 driver functionality.

Implements sf_cellular_api_t::close This function deactivates the PDP context and de-initializes the lower level interface

Parameters

[in]

p_ctrl

Cellular control block

Return values

SSP_SUCCESS	Cellular Driver stop successfully.
SSP_ERR_NOT_OPEN	Device is not opened.
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_CELLULAR_FAILED	Driver un-initialization failed
SSP_ERR_IN_USE	Device already in use
SSP_ERR_CELLULAR_INVALID_STATE	Module in Data mode can't send AT command

Get Mutex

close module

Set module open flag and delete mutex

Delete is used in close API where all resources are released, hence no need to check the return code

The return code is not checked here because tx_mutex_put cannot fail when called with a mutex owned by the current thread. The mutex is owned by the current thread because this call follows a successful call to tx_mutex_get.

The return code is not checked here because tx_mutex_put cannot fail when called with a mutex owned by the current thread. The mutex is owned by the current thread because this call follows a successful call to tx_mutex_get.

sf_cellular_qctlcatm1_config_set()

ssp_err_t sf_cellular_qctlcatm1_config_set	(	sf_cellular_ctrl_t *	p_ctrl,
		sf_cellular_cfg_t const *	p_cfg
	)

Set Cellular device interface configuration.

Parameters

[in]	p_ctrl	Pointer to cellular control block
[in]	p_cfg	Pointer to Cellular configuration

Return values

SSP_SUCCESS	Success
SSP_ERR_CELLULAR_CONFIG_FAILED	Failed Cellular configuration
SSP_ERR_CELLULAR_INIT_FAILED	Failed due to invalid response received from modem

Local configuration variable

Set Preferred Operators List

Set Cellular operator select mode, in case of manual set operator details

Set cellular SIM priority effect. Due to the unavailability of SIM priority effect command in all the BG96 firmwares do not check the return value of this API

set cellular network fallback sequence

Set TimeZone update mode policy

sf_cellular_qctlcatm1_get_imsi()

ssp_err_t sf_cellular_qctlcatm1_get_imsi	(	sf_cellular_instance_cfg_t *	p_celr_instance,
		uint8_t *	p_imsi
	)

Read IMSI ID.

Parameters

[in]	p_celr_instance	Pointer to cellular instance
[out]	p_imsi	IMSI ID

Return values

SSP_SUCCESS	Read IMSI successfully
SSP_ERR_CELLULAR_FAILED	Reading IMSI failed

AT Command used AT+CIMI - Read IMSI

Get response wait time in ticks

Send command to read IMEI number

Expected bytes of successful response

Clear response buffer

Read command response

Ignore first 2 bytes of resp_buff which contains newline ascii character

Reset result value

Delay for next try

SF_CELLULAR_QCTLCATM1_InfoGet()

ssp_err_t SF_CELLULAR_QCTLCATM1_InfoGet	(	sf_cellular_ctrl_t *const	p_ctrl,
		sf_cellular_info_t *const	p_cellular_info
	)

Get Cellular module information.

Implements sf_cellular_api_t::infoGet Get Cellular module information like chipset/driver information, RSSI, noise level, link quality

Parameters

[in]	p_ctrl	Cellular control block
[in]	p_cellular_info	Cellular information structure

Return values

SSP_SUCCESS	Successfully get the Cellular information
SSP_ERR_NOT_OPEN	Driver not opened.
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_CELLULAR_FAILED	Failed reading Cellular information
SSP_ERR_IN_USE	Device already in use
SSP_ERR_CELLULAR_INVALID_STATE	Module in Data mode can't send AT command

Get Mutex

The return code is not checked here because tx_mutex_put cannot fail when called with a mutex owned by the current thread. The mutex is owned by the current thread because this call follows a successful call to tx_mutex_get.

SF_CELLULAR_QCTLCATM1_NetworkStatusGet()

ssp_err_t SF_CELLULAR_QCTLCATM1_NetworkStatusGet	(	sf_cellular_ctrl_t *const	p_ctrl,
		sf_cellular_network_status_t *	p_network_status
	)

Get Network Status information.

Implements sf_cellular_api_t::networkStatusGet

Parameters

[in]	p_ctrl	Cellular control block
[out]	p_network_status	Cellular network structure

Return values

SSP_SUCCESS	Successfully read the Network status information
SSP_ERR_NOT_OPEN	Cellular driver is not opened
SSP_ERR_CELLULAR_FAILED	Failed reading Network Status information.
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_IN_USE	Device already in use
SSP_ERR_CELLULAR_INVALID_STATE	Module in Data mode can't send AT command

Get Mutex

The return code is not checked here because tx_mutex_put cannot fail when called with a mutex owned by the current thread. The mutex is owned by the current thread because this call follows a successful call to tx_mutex_get.

SF_CELLULAR_QCTLCATM1_Open()

ssp_err_t SF_CELLULAR_QCTLCATM1_Open	(	sf_cellular_ctrl_t *	p_ctrl,
		sf_cellular_cfg_t const *const	p_cfg
	)

Initialize Cellular Quectel CATM1 Cellular driver.

Implements sf_cellular_api_t::open Initializes driver and configures module with given parameters and saves this configuration.

Parameters

[out]	p_ctrl	Cellular control block
[in]	p_cfg	Cellular configuration structure

Return values

SSP_SUCCESS	Driver initialization successfully.
SSP_ERR_ALREADY_OPEN	Cellular QuecTel CATM1 Driver is already opened.
SSP_ERR_CELLULAR_CONFIG_FAILED	Cellular QuecTel CATM1 module Configuration failed
SSP_ERR_CELLULAR_INIT_FAILED	Cellular QuecTel CATM1 module initialization failed
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_CELLULAR_FAILED	Driver initialization failed
SSP_ERR_IN_USE	Device already in use

Create Mutex for Synchronization

Get Mutex Lock

The return code is not checked here because tx_mutex_put cannot fail when called with a mutex owned by the current thread. The mutex is owned by the current thread because this call follows a successful call to tx_mutex_get.

SF_CELLULAR_QCTLCATM1_ProvisioningSet()

ssp_err_t SF_CELLULAR_QCTLCATM1_ProvisioningSet	(	sf_cellular_ctrl_t *const	p_ctrl,
		sf_cellular_provisioning_t const *const	p_cellular_provisioning
	)

Sets the provisioning information.

Implements sf_cellular_api_t::provisioningSet Sets Cellular's provisioning information

Parameters

[in]	p_ctrl	Cellular control block
[in]	p_cellular_provisioning	Cellular provisioning structure

Return values

SSP_SUCCESS	Successfully set the provisioning information.
SSP_ERR_NOT_OPEN	Device not opened
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_CELLULAR_FAILED	Provisioning configuration failed
SSP_ERR_IN_USE	Device already in use
SSP_ERR_CELLULAR_INVALID_STATE	Module in Data mode can't send AT command

Get Mutex

Set AirPlane Mode on

The return code is not checked here because tx_mutex_put cannot fail when called with a mutex owned by the current thread. The mutex is owned by the current thread because this call follows a successful call to tx_mutex_get.

SF_CELLULAR_QCTLCATM1_Reset()

ssp_err_t SF_CELLULAR_QCTLCATM1_Reset	(	sf_cellular_ctrl_t *const	p_ctrl,
		sf_cellular_reset_type_t	reset_type
	)

Reset the module.

Implements sf_cellular_api_t::reset This function reset the module as per the reset type

Parameters

[in]	p_ctrl	Cellular control block
[in]	reset_type	Type of reset

Return values

SSP_SUCCESS	Cellular Driver stop successfully.
SSP_ERR_NOT_OPEN	Device is not opened.
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_CELLULAR_FAILED	Driver un-initialization failed
SSP_ERR_IN_USE	Device already in use
SSP_ERR_CELLULAR_INVALID_STATE	Module in Data mode can't send AT command
SSP_ERR_CELLULAR_INIT_FAILED	Failed due to invalid response received from modem

Get Mutex

Reset module

Check whether SIM Pin is required

The return code is not checked here because tx_mutex_put cannot fail when called with a mutex owned by the current thread. The mutex is owned by the current thread because this call follows a successful call to tx_mutex_get.

SF_CELLULAR_QCTLCATM1_VersionGet()

ssp_err_t SF_CELLULAR_QCTLCATM1_VersionGet

(

ssp_version_t *const

p_version

)

Get driver version based on compile time macros.

Implements sf_cellular_api_t::versionGet.

Parameters

[out]

p_version

Common version structure

Return values

SSP_SUCCESS	Success.
SSP_ERR_ASSERTION	The parameter p_version is NULL.