Renesas Synergy Application Note
Application Note
Renesas Synergy™ Platform
Cellular Framework
Introduction
This Application Note will enable you to use a Cellular Framework module in your own design. Upon
completion of this application project, you will be able to add this module to your own design, configure it
correctly for the target application, and write code using the included application code as a reference and
starting point. References to more detailed API descriptions and suggestions of other applications, that
describe advanced uses of the module are available on the Renesas Synergy
referenced in the reference section of this document and should be a valuable resource for creating more
complex designs.
The Cellular Framework module is a high-level application layer interface for the cellular modem integration
on the SSP Application Framework and provides sets of APIs to provision, configure and to communicate
with the cellular network for data communication. Cellular Framework uses the SSP Application Framework
(console framework) to communicate with the Cellular modems with serial interface by using AT commands
internally. SSP Application framework also creates the serial data pipe over serial interface for the data
™
communication, leverag ing the PP P W AN protoc ol pro vi ded b y NetX
. Any TCP/IP communication can be
established over this Wide Area Network (WAN) link using the sockets, NetX Application protocols, and IoT
protocols such as MQTT or COAP.
The Cellular Framework also provides the framework level Socket APIs to communicate with the TCP/IP
stack present on-chip (inside cellular hardware module) in certain cellular hardware modules and there by
communicating with the inter net network, using the socket APIs.
™
Knowledge Base as
Required Resources
To build and run the Cellular Framework Application example, you need:
• Renesas Synergy™ PK-S5D9 kit
2
• e
studio ISDE v7.3.0 or later, or IAR Embedded Workbench® for Renesas Synergy™ v8.23.3 or later
• Synergy Software Package (SSP) 1.6.0 or later, or Synergy Standalone Config ur ator (S SC) 7.3.0 or later
• SEGGER J-Link
• Renesas Synergy USB CDC driver for Windows
®
and its associated USB driver
®
7 (attached in the bundle)
• Windows 7/10 test PC with Console Application like Tera Term or equivalent application installed.
• NimbeLink
™
LTE CAT3 Cellular modem with PMOD adaptor module (Part Num. NL-SW-LTE-TSVG for
North America)
• NimbeLink
™
LTE CAT1 Cellular modem with PMOD adaptor module (Part Num. NL-SW-LTE-GELS3-B
for North America)
• Quectel BG 96 CATM1 Cellular modem with Arduino shield (Rev F board)
• SIM card from the service provider
• Micro USB cables
• Download all the required Renesas (SSP) from the Renesas Synergy
™
Gallery
(https://synergygallery.renesas.com).
Prerequisites and Intended Audience
This application note assumes you have some experience with e
well as the Synergy Software Package (S SP). Bef ore per f orming application note procedures, build and run
the Blinky project in the SSP User Manual. Doing so enables you to become familiar with e
SSP, and ensure that the debug connection to your board functions properly.
2
studio ISDE or IAR EW for Synergy, as
2
studio and the
In addition, this application note assumes you have some knowledge of Cellular networks, as well as 3GPP
standards and communication protocols. Also helpful is an understanding of TCP/IP and its layered
architecture, LAN technologies, WAN technologies, BSD socket communications, and so on.
The intended audience are users who want to develop applications with a Cellular framework module using
S3, S5, S7 Synergy MCU Series.
R30AN0311EU0105 Rev.1.05 Page 1 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
Contents
1. Cellular Framework Module Overview ..................................................................................... 3
1.1 Major Blocks of the Cellular Framework.................................................................................................. 3
2. Cellular Framework Module Operational Overview .................................................................. 4
2.1 Cellular Framework Module Initialization ................................................................................................ 5
2.2 Cellular Hardware Module Pr ovis io ning .................................................................................................. 5
2.3 Application Flow Control Using Socket Interface .................................................................................... 6
2.4 Cellular Packet Transmission .................................................................................................................. 7
2.5 Cellular Packet Reception ....................................................................................................................... 8
2.6 Cellular Framework Module Important Operational Notes and Limitations............................................. 8
3. Cellular Framework Module APIs Overview ............................................................................. 8
3.1 Cellular Framework API ........................................................................................................................ 12
3.2 Cellular Framework Socket Interface API ............................................................................................. 17
4. Including the Cellular Framework Module in an Application ................................................... 24
4.1 Including the Cellular Framework Module with NetX as TCP/IP Stack ................................................. 24
4.2 Including the Cellular Framework Module with On-chip Stack for TCP/IP ............................................ 27
5. Configuring the Cellular Framework Module .......................................................................... 29
5.1 Configuring Cellular Framework with NetX as TCP/IP Stack ................................................................ 29
5.2 Configuring Cellular Fram ew ork with BSD Socket ................................................................................ 36
6. Using the Cellular Framework Module in an Application ........................................................ 36
7. Cellular Framework Module Application Project ..................................................................... 37
7.1 Cellular Application Software Architecture Overview ............................................................................ 38
8. Running the Cellular Framework Module Application Project ................................................. 57
8.1 Cellular Hardware Module Activation and Setup Details ...................................................................... 58
8.2 PK-S5D9 Board Setup Details .............................................................................................................. 59
8.3 Run the Sample Application .................................................................................................................. 61
8.4 Install the USB CDC Device Driver ....................................................................................................... 66
9. Cellular Framework Module Conclusion ................................................................................. 67
10. Cellular Framework Module Next Steps ................................................................................. 67
11. Reference Information ........................................................................................................... 68
Revision History ............................................................................................................................ 70
R30AN0311EU0105 Rev.1.05 Page 2 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
1. Cellular Framework Module Overview
The Cellular framework provides a generic interface for the applications to communicate with the Cellular
hardware module, from various vendors without writing the vendor specific interface code. The framework
mainly consists of common set of APIs’, to interface to the networking stack and generic interface driver for
the different Cellular hardware modules. This section introduces the Cellular framework’s basic blocks and
key features that enables you to determine whether the intended Cellular application can be developed using
the Cellular framework.
The application is abstracted from the underlying vendor driver code by the framework. With the Generic
API’s and abstraction, the applications developed for the cellular hardware module can be easily ported with
another cellular hardware module. The networking stack NetX is also integrated with the framework using the
Network Software Abstraction Layer (NSAL).
1.1 Major Blocks of the Cellular Framework
The Synergy Cellular Framework consists of the following logical blocks:
• Synergy Cellular Framework Application Interface
• Network Stack Abstraction Layer (NSAL) for NetX TCP/IP stack
• Cellular Device Driver
• BSD Socket compatible APIs for interfacing with Cellular hardware module that supports on-chip
networking stack
• Synergy Software Package (SSP) HAL Interface
Figure 1. Cellular Framework Module Organization and Interface Layers
R30AN0311EU0105 Rev.1.05 Page 3 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
1.1.1 Cellular Framework Application Layer Interface
The Cellular Framework provides a common set of interfaces for the application to configure, provision and
to communicate with the Cellular hardware module. By using these Generic interfaces, the user can develop
the Cellular based application using Synergy MCUs. The Cellular hardware module has various configuration
parameters as specified by the family of 3GPP standards. It is possible that individual device drivers and/or
Cellular chipsets/modules will not support configuration of all parameters. At a bare minimum, the network
operator, Access Point Name (APN) and security credentials are required to make the module functional.
1.1.2 Network Stack Abstraction Layer
The Cellular Framework provides a network stack abstraction layer (NSAL). NSAL is layer which connects
the NetX and the Cellular driver by using (PPP) stack that is used for the data communication over WAN link.
1.1.3 Socket Interface Layer
The Cellular Framework provides a Socket level API for the application to interact with the on-chip
networking stack present on the Cellular hardware module. This requires the Cellular hardware
module/driver to support an on-chip networking stack and socket interface. When the application uses these
APIs, it uses the on-chip networking stack present on the Cellular hardware module and does not use the
NSAL or the NetX and its Socket APIs and does not use the Networking stack running on the Synergy MCU
Group.
1.1.4 PPP Stack
Point to point protocol (PPP) is widely used WAN protocol in the Data communication. NetX provides the
PPP stack support as part of the SSP. NSAL leverages the PPP stack to communicate over the serial
interface to the cellular service provider’s network. PPP provides options that handles authentication
methods like PAP/CHAP. Although these authentication mechanisms are optional, NSAL makes use of
framework APIs to send/receive data from the Cellular hardware module. NSAL allows the cellular device
driver to be re-used without any changes specific to the network stack.
1.1.5 Cellular Device Driver
Cellular Framework uses the AT command set to interact with the Cellular modem using the serial driver.
The serial interface used to interact with the modem is UART. The UART speed used in the framework
defaults are up to 115200bits/sec.
2. Cellular Framework Module Operational Overview
Figure 1 shows the user application perspective, in which the application can be used in two different paths
for the communication using the framework depending on the support available on the Cellular modems.
Some modules provide options to use the TCP/IP stack at the Host end and other modules provide options
to use the TCP/IP stack present on the Cellular modem itself. In some cases, cellular hardware module
provides both. When the host TCP/IP stack (NetX) is used, the logical layers of NetX, NSAL, PPP are used
as described in the Architecture diagram. When the on-chip stack is used, the Socket APIs are used to
communicate with the TCP/IP stack present on the Cellular modem. However, the user cannot use both at
the same time.
R30AN0311EU0105 Rev.1.05 Page 4 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
2.1 Cellular Framework Module Initialization
As shown below in the control flow diagram, during the initialization using the configuration supplied by the
user as required for the Cellular modem, NetX nx_ip_create is called that internally invokes the NSAL
driver entry function that takes care of the link level initialization and initializes the cellular hardware module.
In addition, it provisions the module and establishes the Network connection using the PPP interface.
Figure 2. Cellular Framework Module Initialization Sequence
2.2 Cell ul ar Hardware Module Provisioning
Provisioning of the part of the provisioning structure. The arguments used for provisioning is done using the
control structure and the user configured parameter as the provision of the Cellular modem are the
authentication, APN, username and password. In the case of the Cellular Framework, the callback function
provisions the module. You are required to give the APN name, Authentication type and other details
required for provisioning of the module.
R30AN0311EU0105 Rev.1.05 Page 5 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
2.3 Application Flow Control Using Socket Interface
The following diagram shows the flow for the on-chip stack path usage with the Cellular Socket interface.
Figure 3. Cellular Framework Module Socket Interface
R30AN0311EU0105 Rev.1.05 Page 6 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
2.4 Cellular Packet Transmission
The following flow diagram shows the sequence of steps that the Packet transmission uses for the NetX
application.
Figure 4. Cellular Framework Packet Transmission Sequence
R30AN0311EU0105 Rev.1.05 Page 7 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
2.5 Cellular Packet Reception
The flow diagram in the below, shows the Packet reception for the Cellular Framework using NetX. In the
case of receive when the data is received on the serial interface, the processing thread triggers the callback
function and the callback functions handles the data and sends it to the NetX layers for further processing.
Figure 5. Cellular Framework Packet Reception Sequence
2.6 Cellular Framework Module Important Operational Notes and Limitations
• The current framework supports the NimbeLink CAT3, CAT1 and Quectel BG96 Cellular hardware
module only.
• Firmware upgrade over air (FOTA) is not supported by NimbeLink CAT3 and CAT1 Cellular hardware
module.
Refer to the latest SSP Release Notes for any additional operational limitations for this module.
3. Cellular Framework Module APIs Overview
The Cellular Framework module defines a set of APIs for interacting with the underlying modules using the
generic interface. The following are the APIs used by the Cellular framework to communicate with the driver
and cellular hardware module. Most of the Cellular framework APIs uses the p_ctrl and p_cfg data
structures as part of the API that are created when the instance is created. For quick and better
understanding of the API, the structure and some of its details are explained here. For more information on
the instance structure refer the SSP User Manual.
R30AN0311EU0105 Rev.1.05 Page 8 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
sf_cellular_ctrl_t
* p_ctrl;
Pointer to the control structure for the Cellular framework
instance
sf_cellular_cfg_t
const *
p_cfg;
Pointer to the config structure for the cellular framework
instance
sf_cellular_api_t
const *
p_api;
Pointer to the API structure for the cellular framework
sf_cellular_op_select_mo
op_select_mode
Cellular Operator selection mode. There
automatic)
sf_cellular_op_t
op
Cellular operator. Valid when operator
the name format.
uint16_t
num_pref_ops
Number of preferred cellular operators in
preferred Operator list
sf_cellular_op_t
pref_ops
COUNT]
Array of structures describing preferred
sf_cellular_timezone_upd
tz_upd_mode
TimeZone update mode policy. This is the
update(enable/disable)
uint8_t
* p_sim_pin
SIM Pin. If the SIM has Pin which is
here
uint8_t
* p_puk_pin
PUK Pin. Personal Unlocking Key (PUK),
of PIN protection.
ssp_err_t
(* p_prov_callback)
ck_args_t * p_args)
Pointer to provisioning callback function,
This instance structure encompasses everything that is needed to use an instance for the Cellular framework
interface. Most of the API uses the control and config structure as parameters when it is used from the
application.
typedef struct st_sf_cellular_instance
{
instance
} sf_cellular_instance_t;
The following structure shows the Cellular configuration parameters that are part of the configuration
structure. Some of these parameters are configured via the configurator. This config information is used by
the underlying drivers when the API’s are called.
typedef struct st_sf_cellular_cfg
{
de_t
ate_mode_t
[SF_CELLULAR_MAX_
PREFFERED_OPERATOR_
are 4 different options available for the
operation mode selection.
Auto (Automatic Operator Selection)
Manual (Manual Operator Selection)
De-register (De-register from the network)
Manual Fallback (Manual with fallback to
selection mode is manual mode. This is
structure within the config structure that
keeps the Cellular Operator Name and
the pref_ops array. User can have
operators
option for automatic time zone
required to unlock, it can be configured
(sf_cellular_callba
R30AN0311EU0105 Rev.1.05 Page 9 of 70
Apr.26.19
is used in 3GPP mobile phones to reset
a personal identification number (PIN) that
has been lost or forgotten. Most Cellular
Modems offer the feature
used in NSAL
Renesas Synergy™ Platform Cellular Framework
void
(* p_recv_callback)
This is the receive callback function used
void
const * p_context
User defined context passed into callback
function
void
const * p_extend
Instance specific configuration for any
sf_cellular_at_cmd_set_t
const * p_cmd_set
Pointer to Instance specific AT command
set
void
* p_driver_handle
Stores information required by underlying Cellular
device driver.
uint8_t
Apn
[SF_CELLULAR_MAX_STRING_LEN]
Access Point Name
sf_cellular_auth_type_t
auth_type
Authentication type:
PAP/CHAP
uint8_t
Username
[SF_CELLULAR_MAX_STRING_LEN]
User name used for
uint8_t
Password
[SF_CELLULAR_MAX_STRING_LEN]
Password used for
sf_cellular_airplane_mode_t
airplane_mode
Airplane mode
uint8_t
context_id
Context ID to be used for
connection
sf_cellular_pdp_type_t
pdp_type
PDP Type for Context
uint8_t
mfg_name[SF_CELLULAR_MFG_NAME_LEN]
Manufacturer name
uint8_t
chipset[SF_CELLULAR_CHIPSET_LEN]
Pointer to string showing Cellular
chipset/driver information.
uint8_t
fw_version[SF_CELLULAR_FWVERSION_LEN]
Cellular firmware version
uint8_t
imei[SF_CELLULAR_IMEI_LEN]
IMEI number
uint16_t
rssi
Received signal strength
indication
uint16_t
ber
Bit rate error
(sf_cellular_callba
ck_args_t * p_args)
} sf_cellular_cfg_t
typedef struct st_sf_cellular_ctrl
{
} sf_cellular_ctrl_t
3.1 Cell ul ar provisioning information structure
typedef struct st_sf_cellular_provisioning
{
by NetX which will take a data packet
from the Cellular hardware module and
hand it over to NetX for further processing
extended configuration
} sf_cellular_provisioning_t
3.2 Cell ul ar info structure information
typedef struct st_sf_cellular_info
{
} sf_cellular_info_t
authentication
authentication
R30AN0311EU0105 Rev.1.05 Page 10 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
uint32_t
rx_bytes
Bytes received successfully
uint32_t
tx_bytes
Bytes transmitted successfully
uint32_t
rx_err
Bytes receive errors
uint32_t
tx_err
Bytes transmit errors
uint16_t
country_code
Country code
uint16_t
operator_code
Operator code
uint16_t
rssi
RSSI
uint8_t
cid[SF_CELLULAR_CID_LEN]
Cell ID
uint8_t
imsi[SF_CELLULAR_IMSI_LEN]
IMSI
uint8_t
op_name[SF_CELLULAR_MAX_OPERATOR_NAME_LEN]
Operator name
uint8_t
service_domain
Service Domain
Uint8_t
active_band
Active Band
SF_CELLULAR_RESET_TYPE_SOFT
Soft reset module using AT command
SF_CELLULAR_RESET_TYPE_HARD
Hard reset module by toggling Reset Pin
Error Code
Description
SSP_ERR_CELLULAR_CONFIG_FAILED
Cellular module Configuration failed
SSP_ERR_CELLULAR_INIT_FAILED
Cellular module initialization failed.
SSP_ERR_CELLULAR_TRANSMIT_FAILED
Transmission failed
SSP_ERR_CELLULAR_FW_UPTODATE
Firmware is up to date
SSP_ERR_CELLULAR_FW_UPGRADE_FAILED
Firmware upgrade failed
SSP_ERR_CELLULAR_FAILED
Cellular Failed.
3.3 The s ta ti stic and error counters for the cellular instance
typedef struct st_sf_cellular_stats
{
} sf_cellular_stats_t
3.4 The Cellular network status structure
typedef struct st_sf_cellular_network_status
{
} sf_cellular_network_status_t
3.5 Cellular Hardware Module reset type
Typedef enum e_sf_cellular_reset_type
{
} sf_cellular_reset_type_t
Table 1. ssp_err_t (SSP Error Codes):
Note: These are error codes returned by the SSP when the API is used. The table lists error codes specific
to the Cellular framework. For more information and the entire SSP Error codes refer the SSP User
Manual or the (synergy/ssp/inc/ssp_common_api.h).
R30AN0311EU0105 Rev.1.05 Page 11 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
p_cfg
In
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (*open) (sf_cellular_ctrl_t * p_ctrl,sf_cellular_cfg_t const * const
p_cfg)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (*close) (sf_cellular_ctrl_t * p_ctrl)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
p_cellular_provisioning
Out
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (* provisioningGet) (sf_cellular_ctrl_t *
p_cellular_provisioning)
3.6 Cellular Framework API
3.6.1 open
It initializes and enables the Cellular hardware module for data transfers. It does initial driver configuration,
enables the driver link, enables interrupts and makes the device ready for data transfer.
3.6.2 close
Description: It de-initializes and disables the Cellular hardware module for any communication. It deactivates
the PDP context.
Table 1. ssp_err_t (SSP Error Codes):
3.6.3 provisioningGet
Description: It gets the provisioning information for the cellular hardware module
const p_ctrl, sf_cellular_provisioning_t * const
R30AN0311EU0105 Rev.1.05 Page 12 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
p_cellular_provisioning
In
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (* provisioningSet) (sf_cellular_ctrl_t *
const p_cellular_provisioning)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
p_cellular_info
Out
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (* infoGet) (sf_cellular_ctrl_t * const p_ctrl,
sf_cellular_info_t * const p_cellular_info)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
p_cellular_device_stats
Out
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (* statisticsGet) (sf_cellular_ctrl_t * const
p_cellular_device_stats)
3.6.4 provisioningSet
Description: It sets the provisioning information for the cellular hardware module.
const p_ctrl, sf_cellular_provisioning_t const *
3.6.5 infoGet
Description: It Reads the Cellular hardware module's information.
3.6.6 statisticsGet
Description: It Returns statistics information of Cellular hardware module.
p_ctrl, sf_cellular_stats_t * const
R30AN0311EU0105 Rev.1.05 Page 13 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
p_buf
In
Pointer to packet buffer to transmit
length
In
Length of packet buffer
Return values
See Table 1
Function Prototype
ssp_err_t (* transmit) (sf_cellular_ctrl_t * const p_ctrl,
uint8_t * const p_buf, uint32_t length)
Parameter
Name
Direction
Description
p_version
Out
p_version pointer to memory location to return version
number Gets the version number of API and SSP Code
Return values
See Table 1
Function Prototype
ssp_err_t (* versionGet)(ssp_version_t * const p_version)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (* networkConnect) (sf_cellular_ctrl_t * const p_ctrl)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (* networkDisconnect) (sf_cellular_ctrl_t *
const p_ctrl)
3.6.7 transmit
Description: It passes packet buffer to PPP stack for transmission
3.6.8 versionGet
Description: Gets version and stores it in provided pointer p_version.
3.6.9 networkConnect
Description: Initiates the Data connection
3.6.10 networkDisconnect
Description: Terminates the Data connection
R30AN0311EU0105 Rev.1.05 Page 14 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
p_network_status
Out
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (* networkStatusGet) (sf_cellular_ctrl_t * const
p_ctrl, sf_cellular_network_status_t * p_network_status)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
p_old_pin
In
Pointer to char array containing current 4-digit pin
p_new_pin
In
Pointer to char array containing new 4-digit pin
Return values
See Table 1
Function Prototype
ssp_err_t (* simPinSet) (sf_cellular_ctrl_t * const
p_new_pin)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
p_pin
In
PIN number to lock the SIM
Return values
See Table 1
Function Prototype
ssp_err_t (* simLock) (sf_cellular_ctrl_t * const p_ctrl,
uint8_t * const p_pin)
3.6.11 networkStatusGet
Description: Get Network Status information
3.6.12 simPinSet
Description: Set SIM Pin.
3.6.13 simLock
Description: Locks the SIM.
p_ctrl, uint8_t * const p_old_pin, uint8_t * const
R30AN0311EU0105 Rev.1.05 Page 15 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
p_pin
In
PIN number to unlock the SIM
Return values
See Table 1
Function Prototype
ssp_err_t (* simUnlock) (sf_cellular_ctrl_t * const
p_ctrl, uint8_t * const p_pin)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
p_sim_id
Out
SIM ID
Return values
See Table 1
Function Prototype
ssp_err_t (* simIDGet)(sf_cellular_ctrl_t * const p_ctrl,
uint8_t * p_sim_id)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (* fotaCheck) (sf_cellular_ctrl_t * const
p_ctrl)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (* fotaStart) (sf_cellular_ctrl_t * const
p_ctrl)
3.6.14 simUnlock
Description: Unlocks the SIM.
3.6.15 simIDGet
Description: Gets the SIM ID
3.6.16 fotaCheck
Description: Checks for Available Firmware upgrade
3.6.17 fotaStart
Description: Starts the Firmware upgrade
R30AN0311EU0105 Rev.1.05 Page 16 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (* fotaStop) (sf_cellular_ctrl_t * const p_ctrl)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
reset_type
In
Reset Type
Return values
See Table 1
Function Prototype
ssp_err_t (* reset) (sf_cellular_ctrl_t * const p_ctrl,
sf_cellular_reset_type_t reset_type))
sf_cellular_onchip_stack_ctrl_t
* p_ctrl
Pointer to the control structure for the
Cellular framework instance
sf_cellular_onchip_stack_cfg_t
const *
p_cfg
Pointer to the config structure for the cellular
framework instance
sf_cellular_onchip_stack_api_t
const *
p_api
Pointer to the API structure for the cellular
sf_cellular_instance_t
*p_lower_lvl_cellular
Pointer to SF Cellular instance
3.6.18 fotaStop
Description: Stops the Firmware upgrade
3.6.19 reset
Reset cellular hardware module
3.7 Cellular Framework Socket Interface API
The Cellular Framework module provides a set of APIs for interacting with the Cellular hardware modules
that have an on-chip stack using the socket interface. The following are the APIs used by the Cellular
Framework to communicate with the on-chip stack on the Cellular hardware module. Framework provides
two sets of APIs to communicate with the on-chip module. The first set of APIs uses the p_ctrl and p_cfg
data structures as part of the API which are created when the instance is created. The second set of APIs
are the socket interface to create TCP/UDP sockets for data communications. For a quick and better
understanding of the API, the structure and its details are explained in the SSP User Manual.
This instance structure encompasses everything that is needed to use an instance for the Cellular framework
interface.
typedef struct st_sf_cellular_onchip_stack_instance
{
} sf_cellular_onchip_stack_instance_t;
typedef struct st_sf_cellular_onchip_stack_ctrl
framework instance
{
} sf_cellular_onchip_stack_ctrl_t
Defines the Cellular configuration parameters
R30AN0311EU0105 Rev.1.05 Page 17 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
sf_cellular_instance_t
const *
p_lower_lvl
Pointer to SF Cellular instance
void
* p_extend
Extended configuration
SF_CELLULAR_CAT3_SOCKET_INVALID_FD
(-1)
Invalid Socket Descriptor
SF_CELLULAR_CAT3_SOCKET_ERROR
(-1)
Error processing Socket API.
SF_CELLULAR_CAT3_SOCKET_SUCCESS
(0)
Socket Success
SF_CELLULAR_CAT1_SOCKET_INVALID_FD
(-1)
Invalid Socket Descriptor
SF_CELLULAR_CAT1_SOCKET_ERROR
(-1)
Error processing Socket API.
SF_CELLULAR_CAT1_SOCKET_SUCCESS
(0)
Socket Success
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
p_cfg
In
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (* open) (sf_cellular_socket_ctrl_t * p_ctrl,
sf_cellular_socket_cfg_t const * const p_cfg)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 1
Return values
See Table 1
Function Prototype
ssp_err_t (* close) (sf_cellular_socket_ctrl_t * const
p_ctrl)
typedef struct st_sf_cellular_onchip_stack_cfg
{
} sf_cellular_onchip_stack_cfg_t;
Table 2. On-chip socket API error codes for CAT3 and CAT1
3.7.1 open
Description: It initializes and enables the Cellular hardware module for data transfers. It does initial driver
configuration, enable the driver link, enable interrupts and makes the device ready for data transfer.
3.7.2 close
Description: Pointer to function which un-initialize the network interface and may put it in low power mode or
power it off. Close the driver, disables the driver link, disable interrupt.
R30AN0311EU0105 Rev.1.05 Page 18 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
Parameter
Name
Direction
Description
p_version
Out
p_version pointer to memory location to return version
Code
Return values
See Table 1
Function Prototype
ssp_err_t (* versionGet) (ssp_version_t * const p_version)
Parameter
Name
Direction
Description
p_ctrl
In
See Table 2
p_cfg
In
See Table 2
Return values
See Table 2
Function Prototype
int socket (int domain, int type, int protocol)
Parameter
Name
Direction
Description
socket_fd
In
Local socket
Return values
See Table 2
Function Prototype
int close (int socket_fd)
Parameter
Name
Direction
Description
socket_fd
In
Local socket
p_local_sock_addr
In
Pointer to local socket address
addrlen
In
Size of sock address structure
Return values
See Table 2
Function Prototype
int bind (int socket_fd, const struct sockaddr *
p_local_sock_addr, socklen_t addrlen)
3.7.3 versionGet
Description: Gets version and stores it in provided pointer p_version.
number Gets the version number of API and SSP
3.7.4 socket
Description: This API creates the socket.
3.7.5 close
Description: This API closes the socket.
3.7.6 bind
Description: This API Bind socket to interface which is identified by IP address
R30AN0311EU0105 Rev.1.05 Page 19 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
Parameter
Name
Direction
Description
socket_fd
In
Local socket
backlog
In
Max number of connection queue
Return values
See Table 2
Function Prototype
int listen (int sockfd, int backlog)
Parameter
Name
Direction
Description
socket_fd
In
Local socket
p_local_sock_addr
In
Pointer to local socket address
addrlen
In
Size of sock address structure
Return values
See Table 2
Function Prototype
int connect (int sockfd, const struct sockaddr *
p_serv_addr, socklen_t addrlen)
Parameter
Name
Direction
Description
sockfd
In
Local socket
p_cliaddr
Out
Pointer to remote socket address which trying to
p_addrlen
Out
Pointer to address length of client socket address
Return values
See Table 2
Function Prototype
int accept (int sockfd, struct sockaddr * p_cliaddr,
socklen_t * p_addrlen)
3.7.7 listen
Description: Listen for TCP connection. Set socket in listen mode for TCP connection
3.7.8 connect
Description: Establish TCP connection with remote socket.
3.7.9 accept
Description: Accept connection request from remote.
connect
R30AN0311EU0105 Rev.1.05 Page 20 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
Parameter
Name
Direction
Description
sockfd
In
Local socket
p_buf
In
Pointer to Data buffer
length
In
Data buffer length
flags
In
Socket flags
Return values
On success, these calls return the number of characters sent. On error, -1
Function Prototype
ssize_t send(int sockfd, const void * p_buf, size_t
length, int flags)
Parameter
Name
Direction
Description
sockfd
In
Local socket
p_buf
Out
Pointer to Data buffer where data will be received
length
In
Maximum length of data which can be received
flags
In
Socket flags
Return values
On success, these calls return the number of characters received. On error,
Function Prototype
ssize_t recv (int sockfd, void * p_buf, size_t length,
int flags)
3.7.10 send
Description: Send data to remote socket.
is returned
3.7.11 recv
Description: Receive data from remote socket.
-1 is returned
R30AN0311EU0105 Rev.1.05 Page 21 of 70
Apr.26.19
Renesas Synergy™ Platform Cellular Framework
Parameter
Name
Direction
Description
sock_fd
In
Local socket
p_buf
Out
Pointer to Data buffer to sent
length
In
Data Buffer length
flags
In
Socket flags
p_dest_addr
In
Pointer to remote socket address where to send data
addrlen
In
Length of the Socket address structure
Return values
On success, these calls return the number of characters sent. On error, -1
Function Prototype
ssize_t sendto (int sockfd, const void * p_buf, size_t
socklen_t addrlen)
Parameter
Name
Direction
Description
sockfd
In
Local socket
p_buf
Out
Pointer to Data buffer where data will be received
length
In
Maximum length of data which can be received
flags
In
Socket flags
p_dest_addr
In
Pointer to remote socket address which has sent data
addrlen
In
Length of the Socket address structure
Return values
On success, these calls return the number of characters received. On error,
Function Prototype
ssize_t recvfrom (int sockfd, void * p_buf, size_t
socklen_t * p_addrlen)
3.7.12 sendto
Description: Send data to remote socket.
is returned
length, int flags, const struct sockaddr * p_dest_addr,
3.7.13 recvfrom
Description: Receive data from remote socket.
-1 is returned
length, int flags, struct sockaddr * p_src_addr,
R30AN0311EU0105 Rev.1.05 Page 22 of 70
Apr.26.19
Loading...