SF CELLULAR Common Interface

SF_Cellular Framework API Common Code. More...

Functions
ssp_err_t	SF_CELLULAR_COMMON_Open (sf_cellular_ctrl_t *p_ctrl, sf_cellular_cfg_t const *const p_cfg)
	Initialize Cellular driver. More...
ssp_err_t	SF_CELLULAR_COMMON_Close (sf_cellular_ctrl_t *const p_ctrl)
	Stop Cellular driver functionality. More...
ssp_err_t	SF_CELLULAR_COMMON_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_COMMON_StatisticsGet (sf_cellular_ctrl_t *const p_ctrl, sf_cellular_stats_t *const p_cellular_device_stats)
	Get the interface statistics. More...
ssp_err_t	SF_CELLULAR_COMMON_Transmit (sf_cellular_ctrl_t *const p_ctrl, uint8_t *const p_buf, uint32_t length)
	Passes packet buffer to PPP stack for transmission. More...
ssp_err_t	SF_CELLULAR_COMMON_ProvisioningGet (sf_cellular_ctrl_t *const p_ctrl, sf_cellular_provisioning_t *const p_cellular_provisioning)
	Reads the provisioning information. More...
ssp_err_t	SF_CELLULAR_COMMON_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_COMMON_NetworkConnect (sf_cellular_ctrl_t *const p_ctrl)
	Establishes the Data connection. More...
ssp_err_t	SF_CELLULAR_COMMON_NetworkConnectWithCGDATA (sf_cellular_ctrl_t *const p_ctrl)
	Establishes the Data connection using AT+CGDATA command. Limitation: This API activates only one PDP Context Id even though AT+CGDATA command actually supports activation of multiple Context Ids in single command. More...
ssp_err_t	SF_CELLULAR_COMMON_NetworkDisconnect (sf_cellular_ctrl_t *const p_ctrl)
	Terminates the connection. More...
ssp_err_t	SF_CELLULAR_COMMON_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_COMMON_SimPinSet (sf_cellular_ctrl_t *const p_ctrl, uint8_t *const p_old_pin, uint8_t *const p_new_pin)
	Set the SIM PIN. More...
ssp_err_t	SF_CELLULAR_COMMON_SimLock (sf_cellular_ctrl_t *const p_ctrl, uint8_t *const p_pin)
	Lock the SIM. More...
ssp_err_t	SF_CELLULAR_COMMON_SimUnlock (sf_cellular_ctrl_t *const p_ctrl, uint8_t *const p_pin)
	Unlock the SIM. More...
ssp_err_t	SF_CELLULAR_COMMON_SimIDGet (sf_cellular_ctrl_t *const p_ctrl, uint8_t *p_sim_id)
	Get SIM ID. More...
ssp_err_t	SF_CELLULAR_COMMON_CommandSend (sf_cellular_ctrl_t *const p_ctrl, sf_cellular_cmd_resp_t *const p_input_at_command, sf_cellular_cmd_resp_t *const p_output, uint32_t const timeout)
	Send AT command directly to Cellular Modem. More...
ssp_err_t	SF_CELLULAR_COMMON_FotaCheck (sf_cellular_ctrl_t *const p_ctrl, void *p_fotacheck)
	Checks for available firmware upgrade. More...
ssp_err_t	SF_CELLULAR_COMMON_FotaStart (sf_cellular_ctrl_t *const p_ctrl, void *p_fotastart)
	Perform the firmware upgrade. More...
ssp_err_t	SF_CELLULAR_COMMON_FotaStop (sf_cellular_ctrl_t *const p_ctrl, void *p_fotastop)
	Stop firmware upgrade. More...

Detailed Description

SF_Cellular Framework API Common Code.

Cellular Framework header files Framework header files for this package HAL Layer communication interface header file

Function Documentation

SF_CELLULAR_COMMON_Close()

ssp_err_t SF_CELLULAR_COMMON_Close

(

sf_cellular_ctrl_t *const

p_ctrl

)

Stop Cellular driver functionality.

Implements sf_cellular_api_t::close This function deactivates the PDP context and Update global variables for future use

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 used
SSP_ERR_CELLULAR_INVALID_STATE	Module in Data mode can't send AT command

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

SF_CELLULAR_COMMON_CommandSend()

ssp_err_t SF_CELLULAR_COMMON_CommandSend	(	sf_cellular_ctrl_t *const	p_ctrl,
		sf_cellular_cmd_resp_t *const	p_input_at_command,
		sf_cellular_cmd_resp_t *const	p_output,
		uint32_t const	timeout
	)

Send AT command directly to Cellular Modem.

This API will send AT command provided by user to the Cellular Modem and will collect the response from the Modem and will send it back to the user. If Modem is in Data Mode when this API is called then Framework will first switch Modem to Command Mode, then send the AT command and collect the response and then switches the Modem back to Data Mode.

Parameters

[in]	p_ctrl	Pointer to the control block for the Cellular module.
[in]	p_input_at_command	Pointer to structure which contains Modem command to send
[in,out]	p_output	Pointer to buffer in which response will be sent to user, Also user will pass the size of the buffer which is pointed by p_output
[in]	timeout	Timeout for which framework will wait for response in milliseconds

Return values

SSP_SUCCESS	Successfully sent AT command and collected response from Cellular modem
SSP_ERR_CELLULAR_FAILED	Failed to either send AT command or collect response from Cellular modem
SSP_ERR_NOT_OPEN	Device is not opened
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_IN_USE	Device already in use

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_COMMON_FotaCheck()

ssp_err_t SF_CELLULAR_COMMON_FotaCheck	(	sf_cellular_ctrl_t *const	p_ctrl,
		void *	p_fotacheck
	)

Checks for available firmware upgrade.

Implements sf_cellular_api_t::fotaCheck Checks for available firmware upgrade.

Parameters

[in]	p_ctrl	Cellular control block
[in]	p_fotacheck	Fota check specific structure

Return values

SSP_ERR_UNSUPPORTED

Functionality not supported

SF_CELLULAR_COMMON_FotaStart()

ssp_err_t SF_CELLULAR_COMMON_FotaStart	(	sf_cellular_ctrl_t *const	p_ctrl,
		void *	p_fotastart
	)

Perform the firmware upgrade.

Implements sf_cellular_api_t::fotaStart Perform the firmware upgrade.

Parameters

[in]	p_ctrl	Cellular control block
[in]	p_fotastart	Fota start specific structure

Return values

SSP_ERR_UNSUPPORTED

Functionality not supported

SF_CELLULAR_COMMON_FotaStop()

ssp_err_t SF_CELLULAR_COMMON_FotaStop	(	sf_cellular_ctrl_t *const	p_ctrl,
		void *	p_fotastop
	)

Stop firmware upgrade.

Implements sf_cellular_api_t::fotaStop Stop firmware upgrade

Parameters

[in]	p_ctrl	Cellular control block
[in]	p_fotastop	Fota stop specific structure

Return values

SSP_ERR_UNSUPPORTED

Functionality not supported

SF_CELLULAR_COMMON_InfoGet()

ssp_err_t SF_CELLULAR_COMMON_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 used
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_COMMON_NetworkConnect()

ssp_err_t SF_CELLULAR_COMMON_NetworkConnect

(

sf_cellular_ctrl_t *const

p_ctrl

)

Establishes the Data connection.

Implements sf_cellular_api_t::networkConnect Establishes the Network Connection

Parameters

[in]

p_ctrl

Cellular control block

Return values

SSP_SUCCESS	Successfully establishes the Network connection
SSP_ERR_NOT_OPEN	Device not opened
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_CELLULAR_FAILED	Failed to establish the Network Connection
SSP_ERR_IN_USE	Device already in used
SSP_ERR_CELLULAR_INVALID_STATE	Module in Data mode can't send AT command

Get Mutex

Enter Data Mode

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_COMMON_NetworkConnectWithCGDATA()

ssp_err_t SF_CELLULAR_COMMON_NetworkConnectWithCGDATA

(

sf_cellular_ctrl_t *const

p_ctrl

)

Establishes the Data connection using AT+CGDATA command. Limitation: This API activates only one PDP Context Id even though AT+CGDATA command actually supports activation of multiple Context Ids in single command.

Implements sf_cellular_api_t::networkConnect Establishes the Network Connection

Parameters

[in]

p_ctrl

Cellular control block

Return values

SSP_SUCCESS	Successfully establishes the Network connection
SSP_ERR_NOT_OPEN	Device not opened
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_CELLULAR_FAILED	Failed to establish the Network Connection
SSP_ERR_IN_USE	Device already in used
SSP_ERR_CELLULAR_INVALID_STATE	Module in Data mode can't send AT command

Get Mutex

Enter Data Mode

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_COMMON_NetworkDisconnect()

ssp_err_t SF_CELLULAR_COMMON_NetworkDisconnect

(

sf_cellular_ctrl_t *const

p_ctrl

)

Terminates the connection.

Implements sf_cellular_api_t::networkDisconnect

Parameters

[in]

p_ctrl

Cellular control block

Return values

SSP_SUCCESS	Successfully disconnect the connection
SSP_ERR_NOT_OPEN	Cellular driver is not opened
SSP_ERR_CELLULAR_FAILED	Failed to terminate the network connection
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

Exit Data Mode

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_COMMON_NetworkStatusGet()

ssp_err_t SF_CELLULAR_COMMON_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_COMMON_Open()

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

Initialize Cellular driver.

Implements sf_cellular_api_t::open Initializes Cellular Driver and Configure the parameters as per the p_cfg Update global variables for future use.

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 Driver is already opened.
SSP_ERR_CELLULAR_CONFIG_FAILED	Cellular module Configuration failed
SSP_ERR_CELLULAR_INIT_FAILED	Cellular module initialization failed
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_CELLULAR_FAILED	Driver initialization failed
SSP_ERR_IN_USE	Device already in used

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_COMMON_ProvisioningGet()

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

Reads the provisioning information.

Implements sf_cellular_api_t::provisioningGet Reads Cellular's provisioning information

Parameters

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

Return values

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

Get Mutex

Copy provisioning info to driver structure

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_COMMON_ProvisioningSet()

ssp_err_t SF_CELLULAR_COMMON_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 used
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

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_COMMON_SimIDGet()

ssp_err_t SF_CELLULAR_COMMON_SimIDGet	(	sf_cellular_ctrl_t *const	p_ctrl,
		uint8_t *	p_sim_id
	)

Get SIM ID.

Implements sf_cellular_api_t::simGetID Get SIM ID

Parameters

[in]	p_ctrl	Cellular control block
[out]	p_sim_id	SIM ID

Return values

SSP_SUCCESS	Successfully get the SIM ID.
SSP_ERR_CELLULAR_FAILED	Failed to get the SIM ID
SSP_ERR_NOT_OPEN	Device is not opened
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_COMMON_SimLock()

ssp_err_t SF_CELLULAR_COMMON_SimLock	(	sf_cellular_ctrl_t *const	p_ctrl,
		uint8_t *const	p_pin
	)

Lock the SIM.

Implements sf_cellular_api_t::simLock

Parameters

[in]	p_ctrl	Cellular control block
[in]	p_pin	SIM Pin

Return values

SSP_SUCCESS	Successfully lock the SIM
SSP_ERR_NOT_OPEN	Cellular driver is not opened
SSP_ERR_CELLULAR_FAILED	Failed to Lock the SIM
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_COMMON_SimPinSet()

ssp_err_t SF_CELLULAR_COMMON_SimPinSet	(	sf_cellular_ctrl_t *const	p_ctrl,
		uint8_t *const	p_old_pin,
		uint8_t *const	p_new_pin
	)

Set the SIM PIN.

Implements sf_cellular_api_t::simSetPin

Parameters

[in]	p_ctrl	Cellular control block
[in]	p_old_pin	Old SIM Pin
[in]	p_new_pin	New SIM Pin

Return values

SSP_SUCCESS	Successfully set SIM Pin
SSP_ERR_NOT_OPEN	Cellular driver is not opened
SSP_ERR_CELLULAR_FAILED	Failed to set the SIM Pin
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_COMMON_SimUnlock()

ssp_err_t SF_CELLULAR_COMMON_SimUnlock	(	sf_cellular_ctrl_t *const	p_ctrl,
		uint8_t *const	p_pin
	)

Unlock the SIM.

Implements sf_cellular_api_t::simUnlock

Parameters

[in]	p_ctrl	Cellular control block
[in]	p_pin	SIM Pin

Return values

SSP_SUCCESS	Successfully unlock the SIM
SSP_ERR_NOT_OPEN	Cellular driver is not opened
SSP_ERR_CELLULAR_FAILED	Failed to unlock the SIM
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_COMMON_StatisticsGet()

ssp_err_t SF_CELLULAR_COMMON_StatisticsGet	(	sf_cellular_ctrl_t *const	p_ctrl,
		sf_cellular_stats_t *const	p_cellular_device_stats
	)

Get the interface statistics.

Implements sf_cellular_api_t::statisticsGet Collect the statistics information of Cellular interface

Parameters

[in]	p_ctrl	Cellular control block
[in]	p_cellular_device_stats	Cellular statistic structure

Return values

SSP_SUCCESS	Successfully get the Statistics information.
SSP_ERR_UNSUPPORTED	Functionality is not supported.
SSP_ERR_NOT_OPEN	Device not opened
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_CELLULAR_FAILED	Failed Reading statistics information
SSP_ERR_IN_USE	Device already in used
SSP_ERR_CELLULAR_INVALID_STATE	Module in Data mode can't send AT command

SF_CELLULAR_COMMON_Transmit()

ssp_err_t SF_CELLULAR_COMMON_Transmit	(	sf_cellular_ctrl_t *const	p_ctrl,
		uint8_t *const	p_buf,
		uint32_t	length
	)

Passes packet buffer to PPP stack for transmission.

Implements sf_cellular_api_t::transmit Send packet buffer to PPP stack

Parameters

[in]	p_ctrl	Cellular control block
[in]	p_buf	transmit byte buffer pointer
[in]	length	Length of data

Return values

SSP_SUCCESS	Successfully send the packet buffer.
SSP_ERR_NOT_OPEN	Device not opened
SSP_ERR_ASSERTION	Argument NULL is passed
SSP_ERR_CELLULAR_FAILED	Transmitting Data failed
SSP_ERR_IN_USE	Device already in used
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.