Cellular

Cellular Overview

Cellular technology refers to the use of radio frequency (RF) communication systems based on a network of geographically distributed cells, each served by a cell tower or base station. It forms the foundation of mobile communication systems, enabling wireless communication for voice, data, and messaging services. Cellular networks are used in mobile phones, IoT devices, and various other wireless communication applications.

Application Interface

The below table captures the functions that are to be called from the application layer.

API Functions
Function	Description
rs_cellular_open	To open the cellular connection
rs_cellular_process	To process the cellular task
rs_cellular_set_config	To configure the cellular instance.
rs_cellular_is_powered	To checks if the cellular module is powered on.
rs_cellular_connect	To connects to the cellular network.
rs_cellular_disconnect	To disconnects from the cellular network.
rs_cellular_is_connected	To Checks if the cellular module is connected to the network.
rs_cellular_get_network_regstatus	To retrieves the network registration status.
rs_cellular_get_status	To retrieves the cellular status.
rs_cellular_set_gps_interval	To sets the GNSS update interval for the cellular instance.
rs_cellular_set_mqtt_config	To configures the MQTT client for the cellular module.
rs_cellular_mqtt_open	To opens an MQTT connection with the provided configuration.
rs_cellular_register_callback	To registers a callback function for cellular operations.
rs_cellular_mqtt_close	To closes an MQTT connection.
rs_get_mqtt_state	To gets the current state of the MQTT connection
rs_cellular_register_mqtt_callback	To registers an MQTT callback function.
rs_cellular_mqtt_connect	To connects to the MQTT broker
rs_cellular_mqtt_disconnect	To disconnects from the MQTT broker.
rs_cellular_mqtt_disconnect	To disconnects from the MQTT broker.
rs_cellular_get_mqtt_connect_req_status	To gets the MQTT connection request status.
rs_cellular_set_mqtt_socket_id	To sets the socket ID for the MQTT connection.
rs_cellular_mqtt_connect_status	To gets the current MQTT connection status
rs_cellular_get_mqtt_status	To gets the publish state of the MQTT client.
rs_cellular_get_mqtt_publish_state	To disconnects from the MQTT broker.
rs_cellular_mqtt_publish_data	To publishes data to an MQTT topic.

Error Code

Every API’s for the Serial returns some success or failure values. Please refer below section,

RAPIDSEA ERROR CODES

Cellular Header Details

Documentation from the relevant header as follows:

Cellular module Specific APIs.

This file contains definitions, constants, and exported variables related to the RS Cellular (C2C) module and cellular communication interfaces.

Author: Embien RAPIDSEA Team
Copyright: Embien Technologies India Pvt. Ltd.

Defines

CELLULAR_DEBUG: Flag to enable debugging for cellular communication.

RS_C2C_OPERATOR_STRING

String sizes for various parameters (operators, IP addresses, etc.)

Length of the operator string

RS_C2C_OPERATORS_LIST: Total size of the operators list buffer (6 operators)

RS_C2C_IPADDR_STRING: Length of the IP address string.

RS_C2C_IPADDR_LIST: Total size for storing 3 IP addresses.

RS_C2C_ERROR_STRING: Size of the error string buffer.

RS_C2C_CONNECT_MAX_ATTEMPT_COUNT

Connection and network settings.

Maximum number of attempts for RS C2C connection

RS_C2C_MAX_NOS: Maximum number of network operators supported by RS C2C.

RS_C2C_MAX_CONNECTIONS: Maximum number of concurrent RS C2C connections // TODO: Double-check from the RS_C2C module datasheet.

RS_C2C_PAYLOAD_SIZE: Maximum payload size for RS C2C communication.

RS_C2C_MFC_SIZE

Sizes for various C2C-related identifiers.

Size of the MFC (Manufacturer Code) string

RS_C2C_PROD_ID_SIZE: Size of the product ID string.

RS_C2C_FW_REV_SIZE: Size of the firmware revision string.

RS_C2C_IMEI_SIZE: Size of the IMEI string.

RS_C2C_IMSI_SIZE: Size of the IMSI string.

RS_C2C_ICCID_SIZE: Size of the ICCID string.

RS_C2C_DATE_SIZE: Size of the date/time string.

RS_CELLULAR_MAX_NUM_RESPONSES

Maximum number of responses for cellular operations.

Maximum number of responses expected from cellular operations

RS_CELLULAR_MAX_ASYNC_NUM_RESPONSES: Maximum number of asynchronous responses.

RET_INVALID_RESP

These constants define response and status flags, used in cellular communication and debugging.

Invalid response

RET_TIMEOUT: Timeout.

RS_RET_NONE

Return flags used in response handling, indicating specific response types.

No response received

RS_RET_CRLF: Carriage return and line feed (CRLF) in response.

RS_RET_OK: Success response(OK)

RS_RET_ARROW: Response with arrow symbol (e.g., “>”)

RS_RET_ERROR: Error response.

RS_RET_CME_ERROR: CME error flag.

RS_RET_CPIN: Response containing SIM PIN information.

RS_RET_QCCID: Response with the ICCID (SIM card ID)

RS_RET_CREG: Response with network registration status.

RS_RET_QLTS: QLTS (Query Location Status) response flag.

RS_RET_CSQ: Signal quality response.

RS_RET_QIACT: Activate context response.

RS_RET_QMT_OPEN: (MQTT) connection open response

RS_RET_QMT_CONNECT: MQTT connection established response.

RS_RET_QMT_DISCONNECT: MQTT connection disconnected response.

RS_RET_QMT_CLOSE: MQTT connection closed response.

RS_RET_QMT_SUB: MQTT subscription response.

RS_RET_QMT_PUB_RES: MQTT publish response.

RS_RET_CONNECT: General connection response.

RS_RET_HTTP_POST_RES: HTTP POST response.

RS_RET_HTTP_GET_RES: HTTP GET response.

RS_RET_HTTP_READ: HTTP read response.

RS_RET_QGPSLOC_RES: GPS location response.

RS_RET_CMS_ERROR: CMS (Short Message Service) error response.

RS_RET_ASYNC_POWER_DOWN

Asynchronous response flags, used for handling async events and notifications from the modem.

Power down event received asynchronously

RS_RET_ASYNC_RDY: Modem is ready (asynchronous response)

RS_RET_ASYNC_AT: AT command received asynchronously.

RS_RET_ASYNC_ATV1: AT command with response mode set to ‘V1’.

RS_RET_ASYNC_ATE0: AT command with echo off (ATE0)

RS_RET_ASYNC_OK: OK response received asynchronously.

RS_RET_ASYNC_READ: Data received asynchronously.

RS_RET_ASYNC_QMT_RECV: Received MQTT message (QMT)

RS_RET_ASYNC_QMT_STAT: MQTT status update (QMT)

RS_RET_ASYNC_URC_CLOSED: URC (Unsolicited Result Code): Connection closed.

RS_RET_ASYNC_URC_RECV: URC: Data received asynchronously.

RS_RET_ASYNC_URC_IN_FULL: URC: Buffer is full.

RS_RET_ASYNC_URC_INCOM: URC: Incoming communication error.

RS_RET_ASYNC_URC_PDPDEACT: URC: PDP deactivation event.

RS_RET_ASYNC_URC_DNS: URC: DNS (Domain Name System) error.

RS_MQTT_POST_GW_INFO_TOPIC: MQTT topic for posting gateway (device) telemetry data, usually used for sending device data to a server.

RS_MQTT_GW_POST_TOPIC: MQTT topic for posting gateway-specific telemetry data, used for transmitting device or gateway metrics.

RS_MQTT_FMW_SUB_TOPIC: MQTT topic for subscribing to device firmware attributes.

RS_MQTT_DEVICE_REQUEST_TOPIC: MQTT topic for making RPC (Remote Procedure Call) requests to the device. This allows sending remote commands to the device.

RS_MQTT_DEVICE_CLAIM_TOPIC: MQTT topic for claiming or provisioning a device by sending a request to the server for device initialization.

RS_MQTT_CONFIG_RESPONSE: MQTT topic for receiving RPC responses from the device. It helps in managing and acknowledging commands sent to the device.

RS_MQTT_PORT_NUM: MQTT port.

RS_MQTT_VERSION: MQTT protocol version.

RS_MAX_MQTT_CONNECTION: Maximum number of allowed MQTT connections.

RS_MAX_HTTP_CONNECTION: Maximum number of allowed HTTP connections.

RS_CELLULAR_MAX_AT_RETRY_COUNT: Maximum AT command retry count.

RS_C2C_SERIAL_TX_FIFO_BUFFER_SIZE: C2C serial Tx buffer size.

RS_C2C_SERIAL_RX_FIFO_BUFFER_SIZE: C2C serial Rx buffer size.

RS_C2C_UART_PORT_INDEX: C2C UART PORT INDEX.

RS_CELLULAR_MAX_COMMAND_STRING_SIZE: Maximum size for the cellular command string.

RS_MQTT_MAX_USER_NAME_SIZE: Maximum size of the MQTT username.

RS_MQTT_MAX_PASSWORD_SIZE: Maximum size of the MQTT password.

RS_MQTT_MAX_HOST_NAME_SIZE: Maximum allowed size for the MQTT broker’s hostname.

RS_MQTT_MAX_CLIENT_ID_SIZE: Maximum allowed size for the MQTT client ID.

RS_MQTT_SUB_TOPIC_SIZE: Maximum size for MQTT subscription topics.

RS_HTTP_MAX_HOST_NAME_SIZE: Maximum size for the HTTP host’s name.

RS_HTTP_MAX_URL_SIZE: Maximum URL size for HTTP requests.

RS_CELLULAR_REASON_POWERED_ON

RS Cellular System Event Reasons.

Cellular module powered ON

RS_CELLULAR_REASON_POWERED_OFF: Cellular module powered OFF.

RS_CELLULAR_REASON_SIM_DETECTED: Cellular module sim detected.

RS_CELLULAR_REASON_NETWORK_REGISTERED: Cellular module network registered.

RS_CELLULAR_REASON_NETWORK_TIME_SYNC: Cellular module network time sync.

RS_CELLULAR_REASON_NETWORK_SIGNAL_QUALITY: Cellular module network signal quality.

RS_CELLULAR_REASON_CONTEXT_ACTIVATED: Cellular module context activated.

RS_CELLULAR_REASON_CONTEXT_DEACTIVATED: Cellular module context deactivated.

RS_CELLULAR_REASON_GOT_IPADDRESS: Cellular module assigned IP address.

RS_CELLULAR_REASON_GNSS_ON: Cellular module GNSS ON.

RS_CELLULAR_REASON_GNSS_DATA_UPDATE: Cellular module GNSS update.

RS_CELLULAR_REASON_MQTT_CONNECTED

MQTT-related Events Reasons.

Cellular module mqtt connected

RS_CELLULAR_REASON_MQTT_DISCONNECTED: Cellular module mqtt disconnected.

RS_CELLULAR_REASON_MQTT_PUBLISH_SUCCESS: Cellular module mqtt publish success.

RS_CELLULAR_REASON_MQTT_PUBLISH_FAILED: Cellular module mqtt publish failure.

RS_CELLULAR_REASON_MQTT_RECEIVE: Cellular module mqtt receive.

RS_HTTP_CONNECTED

HTTP-related Events Reasons.

Cellular module http connected

RS_HTTP_POST_SUCCESS: Cellular module http post success.

RS_HTTP_POST_FAILED: Cellular module http post failure.

RS_HTTP_GET_SUCCESS: Cellular module http get success.

RS_HTTP_GET_FAILED: Cellular module http get failure.

Typedefs

typedef void (*rs_cellular_callback)(rs_handle_t handle, rs_ret_val_t reason, void *ptr_args): Callback for cellular communication.

typedef void (*rs_cellular_mqtt_callback)(rs_handle_t mqtt_handle, rs_ret_val_t reason, void *ptr_args1, void *ptr_args2): Callback for mqtt communication.

typedef void (*rs_cellular_http_callback)(rs_handle_t http_handle, rs_ret_val_t reason, void *ptr_args1, void *ptr_args2): Callback for http communication.

typedef struct tag_rs_net_macaddr rs_net_macaddr_t: Structure MAC address structure

typedef struct tag_rs_net_ipaddr rs_net_ipaddr_t: IP address structure.

typedef struct tag_rs_cellular_config rs_cellular_config_t: Structure for configuring the cellular.

typedef struct tag_rs_cellular_status rs_cellular_status_t: Structure for cellular status.

typedef struct tag_rs_cellular_info rs_cellular_module_info_t: Structure representing cellular module information.

typedef struct tag_rs_gnss_data_info rs_gnss_data_info_t: Structure representing GNSS (Global Navigation Satellite System) data.

typedef struct tag_rs_gnss_status rs_cellular_gnss_t: Structure representing the GNSS status and error code.

typedef struct tag_rs_cellular_mqtt_publish rs_cellular_mqtt_publish_t: Structure representing MQTT publish operation for cellular module.

typedef struct tag_rs_mqtt_config rs_mqtt_config_t: Structure representing an MQTT configuration in cellular module.

typedef struct tag_rs_mqtt_status rs_mqtt_status_t: Structure representing an MQTT communication status in cellular module.

typedef struct tag_rs_cellular_mqtt_instance rs_cellular_mqtt_instance_t: Structure representing an MQTT information in cellular module.

typedef struct tag_rs_cellular_http_req rs_cellular_http_req_info_t: Structure representing an HTTP request in the cellular module.

typedef struct tag_rs_http_config rs_http_config_t: Structure representing an HTTP configuration in cellular module.

typedef struct tag_rs_http_status rs_http_status_t: Structure representing an HTTP communication status in cellular module.

typedef struct tag_rs_cellular_http_instance rs_cellular_http_instance_t: Structure representing an HTTP information in cellular module.

typedef struct tag_cellular_cmd cellular_cmd_t: Structure representing a cellular command.

typedef struct tag_rs_cellular_instance rs_cellular_instance_t: Structure representing cellular instance information.

Enums

enum RS_C2C_Protocol_t

Enumeration Supported protocols in RS C2C protocol

Values:

enumerator RS_C2C_TCP_PROTOCOL: TCP protocol.

enumerator RS_C2C_UDP_PROTOCOL: UDP protocol.

enum cellular_nwk_reg_status_t

Cellular network registration status.

Values:

enumerator REGSTATUS_NOT_REGISTERED: Not registered to any network.

enumerator REGSTATUS_HOME_NETWORK: Registered to home network.

enumerator REGSTATUS_TRYING: Attempting to register.

enumerator REGSTATUS_REG_DENIED: Registration denied.

enumerator REGSTATUS_UNKNOWN: Unknown registration status.

enumerator REGSTATUS_ROAMING: Registered but roaming.

enumerator REGSTATUS_ERROR: Error in registration.

enum RS_C2C_SendStatus_t

Sending status in in RS C2C protocol.

Values:

enumerator RS_C2C_SEND_OK: Data sent successfully.

enumerator RS_C2C_SEND_FAIL: Data sending failed.

enumerator RS_C2C_SEND_ERROR: Error occurred during sending.

enum net_ip_version_t

Network IP version types.

Values:

enumerator NET_IP_V4: IPv4 address.

enumerator NET_IP_V6: IPv6 address.

enum cellular_simstate_t

Cellular SIM states.

Values:

enumerator SIM_READY: SIM is ready for use.

enumerator SIM_PIN_NEEDED: SIM requires PIN entry.

enumerator SIM_ERROR: SIM error occurred.

enum cellular_authent_t

Authentication methods for cellular network.

Values:

enumerator CELLULAR_AUTHENT_NONE: No authentication.

enumerator CELLULAR_AUTHENT_PAP: PAP authentication.

enumerator CELLULAR_AUTHENT_CHAP: CHAP authentication.

enumerator CELLULAR_AUTHENT_PAP_CHAP: PAP and CHAP authentication.

enum tx_state_t

Enumeration for the transmission state.

Values:

enumerator TX_IDLE: Transmission is idle.

enumerator TX_INPROGRESS: Transmission is in progress.

enumerator TX_ERROR: Transmission error occurred.

enum http_req_type_t

Enumeration of HTTP request types.

Values:

enumerator HTTP_REQ_TYPE_POST: HTTP POST request.

enumerator HTTP_REQ_TYPE_GET: HTTP GET request.

enumerator HTTP_REQ_TYPE_GETX: Extended HTTP GET request.

enumerator HTTP_REQ_TYPE_PUT: HTTP PUT request.

Functions

rs_ret_val_t rs_cellular_init()

Functions related to cellular module.

Initializes the cellular module.

This function initializes the cellular module, preparing it for use.

Returns:: 0 on success, error on failure

rs_ret_val_t rs_cellular_process()

Processes cellular functionality.

This function should be called regularly to handle ongoing tasks, such as checking the status of the cellular connection, processing incoming data, etc.

Returns:: 0 on success, error on failure

rs_ret_val_t rs_cellular_task(void)

Processes cellular tasks.

This function should be called to initiate cellular task.

Returns:: 0 on success, error on failure

rs_handle_t rs_cellular_set_config(rs_cellular_config_t *ptr_config, uint8_t u8_port, uint8_t u8_pin, uint8_t *ptr_apn_string, uint8_t *ptr_password, uint8_t *ptr_username, cellular_authent_t authentication_type, uint32_t u32_sync_network_time_interval, uint32_t u32_sync_network_quality_interval, uint8_t u8_gnss_enable, uint32_t u32_gnss_read_interval)

rs_ret_val_t rs_cellular_register_callback(rs_handle_t handle, rs_cellular_callback *ptr_callback_function)

Registers a callback function for cellular operations.

This function registers a callback that will be called when a cellular operation completes.

Parameters:

handle – [in] - The handle to the cellular instance.
ptr_callback_function – [in] - Pointer to the callback function.

Returns:

0 on success, error on failure

rs_handle_t rs_cellular_open(rs_cellular_instance_t *ptr_instance, rs_cellular_config_t *ptr_config)

Opens a cellular connection.

This function opens a cellular connection using the provided instance and configuration.

Parameters:

ptr_instance – [in] - Pointer to the cellular instance structure.
ptr_config – [in] - Pointer to the configuration structure.

Returns:

A handle to the opened cellular instance.

rs_ret_val_t rs_cellular_connect(rs_handle_t handle)

Connects to the cellular network.

This function attempts to establish a connection to the cellular network.

Parameters:: handle – [in] - The handle to the cellular instance.
Returns:: 0 on success, error on failure

rs_ret_val_t rs_cellular_disconnect(rs_handle_t handle)

Disconnects from the cellular network.

This function disconnects the cellular module from the network.

Parameters:: handle – [in] - The handle to the cellular instance.
Returns:: 0 on success, error on failure

rs_handle_t rs_get_cellular_handle()

Retrieves the handle for the current cellular instance.

This function retrieves the handle for the currently active cellular instance.

Parameters:: Nil – [in]
Returns:: The handle to the cellular instance.

rs_ret_val_t rs_set_cellular_handle(rs_handle_t handle)

Sets the handle for the current cellular instance.

This function Sets the handle for the currently active cellular instance.

Parameters:: cellular – [in] handle
Returns:: 0 on success, error on failure

rs_cellular_status_t *rs_cellular_get_status(rs_handle_t handle)

Retrieves the cellular status.

This function retrieves the current status of the cellular module, including network registration status, signal strength, and connection status.

Parameters:: handle – [in] - The handle to the cellular instance.
Returns:: A pointer to the cellular status structure.

cellular_nwk_reg_status_t rs_cellular_get_network_regstatus(rs_handle_t handle)

Retrieves the network registration status.

This function returns the current network registration status of the cellular module.

Parameters:: handle – [in] - The handle to the cellular instance.
Returns:: network status (REGSTATUS_NOT_REGISTERED = 0x00, REGSTATUS_HOME_NETWORK = 0x01, REGSTATUS_TRYING = 0x02, REGSTATUS_REG_DENIED = 0x03, REGSTATUS_UNKNOWN = 0x04, REGSTATUS_ROAMING = 0x05, REGSTATUS_ERROR = 0xFF).

rs_ret_val_t rs_cellular_is_powered(rs_handle_t handle)

Checks if the cellular module is powered on.

This function returns whether the cellular module is powered on or not.

Parameters:: handle – [in] - The handle to the cellular instance.
Returns:: 1 if the cellular module is powered on, 0 otherwise.

rs_ret_val_t rs_cellular_is_connected(rs_handle_t handle)

Checks if the cellular module is connected to the network.

Disconnects from the MQTT broker.

This function returns the connection status of the cellular module.

This function disconnects the MQTT client from the broker.

Parameters:

handle – [in] - The handle to the cellular instance.
mqtt_handle – [in] - The handle for the MQTT connection.

Returns:

1 if the cellular module is connected, 0 otherwise.

Returns:

0 on success, error on failure

rs_ret_val_t rs_cellular_clear_gnss_value()

Clears the GNSS (Global Navigation Satellite System) values.

This function clears the GNSS-related data, including latitude, longitude, and other satellite information.

Parameters:: Nil – [in]
Returns:: 0 on success, error on failure

uint8_t *rs_cellular_get_gnss_lattitude()

Retrieves the GNSS latitude value.

This function returns the latitude from the GNSS data.

Parameters:: Nil – [in]
Returns:: Pointer to the GNSS latitude value as a string.

uint8_t *rs_cellular_get_gnss_longtitude()

Retrieves the GNSS longtitude value.

This function returns the longtitude from the GNSS data.

Parameters:: Nil – [in]
Returns:: Pointer to the GNSS longtitude value as a string.

rs_ret_val_t rs_cellular_set_gps_interval(rs_handle_t handle, uint8_t u8_is_gnss_enable, uint32_t u32_gnss_interval)

Sets the GNSS update interval for the cellular instance.

This function sets the interval at which GNSS data is updated, allowing periodic updates based on the specified GNSS enable flag and interval.

Parameters:

handle – [in] - The handle to the cellular instance.
u8_is_gnss_enable – [in] - Flag to enable or disable GNSS.
u32_gnss_interval – [in] - The interval (in seconds) to update GNSS data.

Returns:

0 on success, error on failure

rs_ret_val_t rs_cellular_set_mqtt_config(rs_mqtt_config_t *ptr_mqtt_config, uint8_t u8_mqtt_version, uint8_t *host_name, uint32_t port_number, uint8_t *user_name, uint8_t *password, uint8_t *client_id, uint8_t *sub_topic_1, uint8_t *sub_topic_2, uint8_t u8_is_ssl_enable, uint8_t u8_ssl_security_level, uint8_t u8_pub_qos_level, uint8_t u8_sub_qos_level)

Configures the MQTT client for the cellular module.

Functions related to MQTT connection ————————————————————

This function sets up the MQTT configuration, including connection details, quality of service levels, and security options.

Parameters:

ptr_mqtt_config – [in] - Pointer to the MQTT configuration structure.
u8_mqtt_version – [in] - The MQTT protocol version.
host_name – [in] - The host name of the MQTT broker.
port_number – [in] - The port number to connect to.
user_name – [in] - The username for authentication with the broker.
password – [in] - The password for authentication with the broker.
client_id – [in] - The MQTT client ID.
sub_topic_1 – [in] - The first topic to subscribe to.
sub_topic_2 – [in] - The second topic to subscribe to.
u8_is_ssl_enable – [in] - Flag to enable SSL/TLS.
u8_ssl_security_level – [in] - SSL/TLS security level.
u8_pub_qos_level – [in] - The Quality of Service level for publishing.
u8_sub_qos_level – [in] - The Quality of Service level for subscribing.

Returns:

0 on success, error on failure

rs_ret_val_t rs_cellular_register_mqtt_callback(rs_handle_t mqtt_handle, rs_cellular_mqtt_callback *ptr_callback_function)

Registers an MQTT callback function.

This function registers a callback to be invoked upon the completion of MQTT operations.

Parameters:

mqtt_handle – [in] - The handle for the MQTT connection.
ptr_callback_function – [in] - Pointer to the callback function.

Returns:

0 on success, error on failure

rs_handle_t rs_cellular_mqtt_open(rs_mqtt_config_t *ptr_config)

Opens an MQTT connection with the provided configuration.

This function opens an MQTT connection using the provided configuration parameters.

Parameters:: ptr_config – [in] - Pointer to the MQTT configuration structure.
Returns:: A handle to the opened MQTT connection.

rs_ret_val_t rs_cellular_mqtt_close(rs_handle_t mqtt_handle)

Closes an MQTT connection.

This function closes an active MQTT connection, freeing resources associated with it.

Parameters:: mqtt_handle – [in] - The handle to the MQTT connection.
Returns:: 0 on success, error on failure

rs_ret_val_t rs_cellular_mqtt_connect(rs_handle_t mqtt_handle)

Connects to the MQTT broker.

This function attempts to establish an MQTT connection to the broker.

Parameters:: mqtt_handle – [in] - The handle for the MQTT connection.
Returns:: 0 on success, error on failure

rs_ret_val_t rs_cellular_mqtt_disconnect(rs_handle_t mqtt_handle)

rs_ret_val_t rs_cellular_get_mqtt_connect_req_status(rs_handle_t mqtt_handle)

Gets the MQTT connection request status.

This function checks the status of the MQTT connection request, indicating whether the connection request is in progress, successful, or failed.

Parameters:: mqtt_handle – [in] - The handle to the MQTT connection.
Returns:: The MQTT connection request status.

rs_ret_val_t rs_cellular_mqtt_connect_status(rs_handle_t mqtt_handle)

Gets the current MQTT connection status.

This function checks if the MQTT client is currently connected to the broker.

Parameters:: mqtt_handle – [in] - The handle for the MQTT connection.
Returns:: The MQTT connection status (0 = not connected, 1 = connected).

rs_ret_val_t rs_cellular_set_mqtt_publish_state(rs_handle_t mqtt_handle, tx_state_t state)

Sets the publish state of the MQTT client.

This function sets the publish state of the MQTT client to the specified state.

Parameters:

mqtt_handle – [in] - The handle for the MQTT connection.
state – [in] - The desired publish state.

Returns:

0 on success, error on failure

tx_state_t rs_cellular_get_mqtt_publish_state(rs_handle_t mqtt_handle)

Gets the publish state of the MQTT client.

This function returns the current publish state of the MQTT client.

Parameters:: mqtt_handle – [in] - The handle for the MQTT connection.
Returns:: The current MQTT publish state.

rs_mqtt_status_t *rs_cellular_get_mqtt_status(rs_handle_t mqtt_handle)

Retrieves the MQTT status.

This function retrieves the status of the MQTT connection, including its current state, message delivery status and error codes.

Parameters:: mqtt_handle – [in] - The handle to the MQTT connection.
Returns:: A pointer to the MQTT status structure.

rs_ret_val_t rs_get_mqtt_state(rs_handle_t mqtt_handle)

Gets the current state of the MQTT connection.

This function returns the current state of the MQTT connection.

Parameters:: mqtt_handle – [in] - The handle to the MQTT connection.
Returns:: The state of the MQTT connection

rs_ret_val_t rs_cellular_mqtt_publish_data(uint32_t u32_mqtt_handle, uint8_t *ptr_mqtt_publish_topic, uint8_t *ptr_publish_data, uint8_t u8_qos_value)

Publishes data to an MQTT topic.

This function publishes the provided data to the specified MQTT topic.

Parameters:

u32_mqtt_handle – [in] - The handle for the MQTT connection.
ptr_mqtt_publish_topic – [in] - Pointer to the topic to publish to.
ptr_publish_data – [in] - Pointer to the data to publish.
u8_qos_value – [in] - The Quality of Service (QoS) level for the publication.

Returns:

A result indicating success or failure of the publish operation.

rs_handle_t get_mqtt_handle_by_socket_id(uint8_t u8_socket_id)

Retrieves the MQTT handle associated with a socket ID.

This function returns the MQTT handle that corresponds to a specific socket ID.

Parameters:: u8_socket_id – [in] - The socket ID for which the handle is to be retrieved.
Returns:: The MQTT handle corresponding to the socket ID.

rs_ret_val_t rs_cellular_set_mqtt_socket_id(rs_handle_t mqtt_handle, uint8_t u8_socket_id)

Sets the socket ID for the MQTT connection.

This function assigns a socket ID to the specified MQTT connection, which can be used for managing multiple MQTT connections.

Parameters:

mqtt_handle – [in] - The handle to the MQTT connection.
u8_socket_id – [in] - The socket ID to assign to the MQTT connection.

Returns:

0 on success, error on failure

rs_ret_val_t rs_cellular_set_http_config(rs_http_config_t *ptr_http_config, uint8_t *host_name, uint8_t *request_header, uint8_t u8_content_type, uint8_t u8_ssl_enable, uint8_t u8_ssl_version, uint8_t u8_ssl_id, uint8_t u8_ssl_security_level)

Configures the HTTP settings for cellular operations.

Functions related to HTTP connection ————————————————————

This function sets up the necessary configuration for HTTP operations, including SSL settings, content type, and request headers.

Parameters:

ptr_http_config – [in] - Pointer to the HTTP configuration structure.
host_name – [in] - Pointer to the host name of the HTTP server.
request_header – [in] - Pointer to the HTTP request headers.
u8_content_type – [in] - The content type for the HTTP request.
u8_ssl_enable – [in] - Flag to enable or disable SSL.
u8_ssl_version – [in] - The SSL version to be used.
u8_ssl_id – [in] - The SSL ID for the connection.
u8_ssl_security_level – [in] - The SSL security level to be applied.

Returns:

0 on success, error on failure

rs_ret_val_t rs_cellular_register_http_callback(rs_handle_t http_handle, rs_cellular_http_callback *ptr_callback_function)

Registers a callback function for HTTP operations.

This function registers a callback to be invoked upon completion of an HTTP operation.

Parameters:

http_handle – [in] - The handle to the HTTP connection.
ptr_callback_function – [in] - Pointer to the callback function.

Returns:

0 on success, error on failure

rs_handle_t rs_cellular_http_open(rs_http_config_t *ptr_config)

Opens an HTTP connection with the provided configuration.

This function opens an HTTP connection using the given configuration.

Parameters:: ptr_config – [in] - Pointer to the HTTP configuration structure.
Returns:: A handle to the HTTP connection.

rs_ret_val_t rs_cellular_http_close(rs_handle_t http_handle)

Closes an active HTTP connection.

This function closes the specified HTTP connection identified by its handle.

Parameters:: http_handle – [in] - The handle to the HTTP connection to close.
Returns:: 0 on success, error on failure

rs_ret_val_t rs_cellular_http_connect(rs_handle_t http_handle)

Initiates the HTTP connection process.

This function attempts to establish a connection to the HTTP server.

Parameters:: http_handle – [in] - The handle to the HTTP connection.
Returns:: 0 on success, error on failure

rs_ret_val_t rs_cellular_http_disconnect(rs_handle_t http_handle)

Disconnects from the HTTP server.

This function disconnects the HTTP connection identified by the provided handle.

Parameters:: http_handle – [in] - The handle to the HTTP connection.
Returns:: 0 on success, error on failure

rs_ret_val_t rs_cellular_get_http_connect_request_status(rs_handle_t http_handle)

Gets the HTTP connection request status.

This function checks the status of an HTTP connection request, returning whether the connection is in progress, successful, or failed.

Parameters:: http_handle – [in] - The handle to the HTTP connection.
Returns:: The connection request status.

rs_ret_val_t rs_cellular_http_connect_status(rs_handle_t http_handle)

Gets the connection status of the HTTP connection.

This function returns whether the HTTP connection is currently active or not.

Parameters:: http_handle – [in] - The handle to the HTTP connection.
Returns:: The HTTP connection status (0 = not connected, 1 = connected).

tx_state_t rs_cellular_get_http_publish_state(rs_handle_t http_handle)

Gets the transmission state of the HTTP connection.

This function etrieves the current transmission state of the HTTP connection.

Parameters:: http_handle – [in] - The handle to the HTTP connection.
Returns:: Retrieves the current transmission state of the HTTP connection

rs_ret_val_t rs_cellular_set_http_publish_state(rs_handle_t http_handle, tx_state_t state)

Sets the publish state of the HTTP connection.

This function sets the current publish state for HTTP transmission.

Parameters:

http_handle – [in] - The handle to the HTTP connection.
state – [in] - The desired publish state for the HTTP connection.

Returns:

0 on success, error on failure

rs_http_status_t *rs_cellular_get_http_status(rs_handle_t http_handle)

Retrieves the status of the HTTP connection.

This function returns the current status of the HTTP connection.

Parameters:: http_handle – [in] - The handle to the HTTP connection.
Returns:: A pointer to the HTTP status structure.

rs_ret_val_t rs_get_http_state(rs_handle_t http_handle)

Gets the current state of the HTTP connection.

This function retrieves the current state of the HTTP connection.

Parameters:: http_handle – [in] - The handle to the HTTP connection to close.
Returns:: The state of the HTTP connection.

rs_ret_val_t rs_cellular_http_post(uint32_t u32_http_handle, uint8_t *ptr_http_post_data)

Sends a POST request over HTTP connection.

This function sends HTTP POST data to the server, identified by the provided handle.

Parameters:

u32_http_handle – [in] - The handle to the HTTP.
ptr_http_post_data – [in] - Pointer to the data to send in the POST request.

Returns:

A result indicating success or failure of the POST request.

rs_ret_val_t rs_cellular_http_getx(uint32_t u32_http_handle, uint8_t *ptr_http_get_data, uint32_t u32_read_offset, uint32_t u32_read_len)

Sends a GETX request over HTTP.

This function sends an HTTP GETX request to the server.

Parameters:

u32_http_handle – [in] - The handle to the HTTP connection.
ptr_http_get_data – [in] - Pointer to the data to be retrieved by the GETX request.
u32_read_offset – [in] - The offset for reading the data.
u32_read_len – [in] - The length of data to read.

Returns:

A result indicating success or failure of the GETX request.

rs_ret_val_t rs_cellular_http_get(uint32_t u32_http_handle, uint8_t *ptr_http_get_data)

Sends an HTTP GET request.

This function sends an HTTP GET request with the specified data.

Parameters:

u32_http_handle – [in] - The handle to the HTTP connection.
ptr_http_get_data – [in] - Pointer to the data to send in the GET request.

Returns:

A result indicating success or failure of the GET request.

rs_cellular_instance_t *rs_get_cellular_instance()

Retrieves the cellular instace pointer.

This function retrieves the ellular instace pointer.

Parameters:: Nil – [in]
Returns:: cellular instance pointer.

void rcb_user_cellular_callback(rs_handle_t handle, rs_ret_val_t reason, void *ptr_args)

Callback function for cellular events.

This function is invoked when a cellular event occurs, such as a connection change or error.

Parameters:

handle – [in] - The handle to the cellular instance.
reason – [in] - The reason for the callback, indicating success or failure.
ptr_args – [in] - Pointer to additional arguments, if any.

Returns:

Void

struct tag_rs_net_macaddr

#include <rs_cellular.h>

Structure MAC address structure

Public Members

uint8_t mac[6]: 6-byte MAC address

struct tag_rs_net_ipaddr

#include <rs_cellular.h>

IP address structure.

Public Members

net_ip_version_t ipv: IP version (IPv4 or IPv6)

uint8_t ip[16]: Binary format. Network byte order. IPv4 mapped IPv6 format. E.g. 10.2.3.4 is ::ffff:a02:304 or 0xFFFF0A020304.

struct tag_rs_cellular_config

#include <rs_cellular.h>

Structure for configuring the cellular.

Public Members

rs_serial_config_t c2c_serial_config: C2C serial configuration.

rs_serial_instance_t c2c_serial_instance: C2C serial instance(Information)

uint8_t tx_fifo[RS_C2C_SERIAL_TX_FIFO_BUFFER_SIZE]: FIFO data buffer of TX.

uint8_t rx_fifo[RS_C2C_SERIAL_RX_FIFO_BUFFER_SIZE]: FIFO data buffer of RX.

uint8_t power_key_port: Cellular module power key port.

uint8_t power_key_pin: Cellular module power key pin.

uint8_t *ptr_apn_string: access point name, string of chars

uint8_t *ptr_password: passoword, string of chars

uint8_t *ptr_username: user name, string of chars

cellular_authent_t authentication_type: Authentication type.

uint32_t u32_get_network_time_update_interval_in_seconds: Network time update interval.

uint32_t u32_get_network_quality_update_interval_in_seconds: Network quality update interval.

uint8_t is_gnss_enable: GNSS support feature enabled.

uint32_t u32_gnss_data_read_interval_in_seconds: GNSS data read interval.

struct tag_rs_cellular_status

#include <rs_cellular.h>

Structure for cellular status.

Public Members

uint8_t ipaddr[16]: IP address.

rs_net_macaddr_t macAddr: MAC address.

uint8_t online: Online.

uint8_t u8_retry_count: Retry count.

uint8_t powered: LTE Power.

uint8_t connect_request: Connect request.

uint8_t u8_connection_attempt_count: Connect retry count.

int signal_quality: Signal Quality.

cellular_nwk_reg_status_t network_status: Network registration status.

cellular_simstate_t sim_status: sim status

struct tag_rs_cellular_info

#include <rs_cellular.h>

Structure representing cellular module information.

Public Members

uint8_t Manufacturer[RS_C2C_MFC_SIZE]: Cellular module manufacturer.

uint8_t ProductID[RS_C2C_PROD_ID_SIZE]: Cellular module product ID.

uint8_t FW_Rev[RS_C2C_FW_REV_SIZE]: Firmware revision of the cellular module.

uint8_t Imei[RS_C2C_IMEI_SIZE]: International Mobile Equipment Identity (IMEI)

uint8_t IMSI[RS_C2C_IMSI_SIZE]: International Mobile Subscriber Identity (IMSI)

uint8_t ICCID[RS_C2C_ICCID_SIZE]: Integrated Circuit Card Identifier (ICCID)

struct tag_rs_gnss_data_info

#include <rs_cellular.h>

Structure representing GNSS (Global Navigation Satellite System) data.

Public Members

uint8_t UTC[16]: Universal Time Coordinated (UTC)

uint8_t latitude[16]: Latitude in decimal degrees.

uint8_t longitude[16]: Longitude in decimal degrees.

uint8_t cog[16]: Course over ground.

uint8_t date[16]: Date in YYYY-MM-DD format.

uint8_t hdop[8]: Horizontal Dilution of Precision.

uint8_t alt[8]: Altitude in meters.

uint8_t spkm[8]: Speed over ground in kilometers per hour.

uint8_t spkn[8]: Speed over ground in knots.

int fix: GNSS fix status (0 = no fix, 1 = fix)

int nsat: Number of satellites used for the fix.

struct tag_rs_gnss_status

#include <rs_cellular.h>

Structure representing the GNSS status and error code.

Public Members

int gnss_error_code: GNSS error code.

rs_gnss_data_info_t gnss_data: GNSS data.

struct tag_rs_cellular_mqtt_publish

#include <rs_cellular.h>

Structure representing MQTT publish operation for cellular module.

Public Members

uint32_t u32_mqtt_handle: Handle for the MQTT connection.

uint8_t *ptr_mqtt_publish_topic: MQTT topic for publishing data.

uint8_t *ptr_publish_data: Data to be published

uint8_t u8_qos_value: Quality of Service level for the MQTT message.

tx_state_t u8_publish_state: Current state of the publish operation.

struct tag_rs_mqtt_config

#include <rs_cellular.h>

Structure representing an MQTT configuration in cellular module.

Public Members

uint8_t u8_mqtt_version: Version for MQTT.

uint8_t u8_host_name[RS_MQTT_MAX_HOST_NAME_SIZE]: Host name for MQTT broker.

uint32_t u32_port_number: Port number for MQTT communication.

uint8_t u8_user_name[RS_MQTT_MAX_USER_NAME_SIZE]: User name for MQTT authentication.

uint8_t u8_password[RS_MQTT_MAX_PASSWORD_SIZE]: Password for MQTT authentication.

uint8_t u8_client_id[RS_MQTT_MAX_CLIENT_ID_SIZE]: Client ID for MQTT connection.

uint8_t u8_sub_topic_1[RS_MQTT_SUB_TOPIC_SIZE]: Client ID for MQTT connection.

uint8_t u8_sub_topic_2[RS_MQTT_SUB_TOPIC_SIZE]: Client ID for MQTT connection.

uint8_t u8_mqtt_pub_qos_level: MQTT publish packet QOS level.

uint8_t u8_mqtt_sub_qos_level: MQTT Subscribe packet QOS level.

uint8_t u8_is_ssl_enable: Flag indicating SSL/TLS encryption status.

uint8_t u8_ssl_security_level: Flag indicating SSL/TLS Security level.

struct tag_rs_mqtt_status

#include <rs_cellular.h>

Structure representing an MQTT communication status in cellular module.

Public Members

uint8_t u8_connect_status: Status of MQTT connection.

uint32_t u32_published_count: Count of successful MQTT publish operations.

uint32_t u32_mqtt_connect_retry_count: Count of MQTT connection retry attempts.

uint32_t u32_mqtt_publish_failed_count: Count of failed MQTT publish operations.

uint32_t u32_mqtt_connect_attempt_count: Count of total MQTT connection attempts.

uint8_t u8_is_mqtt_connection_alive: MQTT connection status.

uint8_t u8_mqtt_connection_error_code: MQTT connection error code.

struct tag_rs_cellular_mqtt_instance

#include <rs_cellular.h>

Structure representing an MQTT information in cellular module.

Public Members

rs_handle_t mqtt_handle: Handle of the Cellular MQTT.

rs_mqtt_config_t *ptr_mqtt_config: Pointer to the MQTT config structure.

uint8_t u8_state: Current state of MQTT module.

uint8_t u8_mqtt_socket_id: Socket ID for MQTT communication.

uint8_t u8_mqtt_connect_request: Flag indicating MQTT connect request.

rs_mqtt_status_t mqtt_status: Pointer to the MQTT status structure.

rs_cellular_mqtt_publish_t mqtt_publish_info: Pointer to the MQTT publish info structure.

rs_cellular_mqtt_callback ptr_cb: Pointer to the callback function.

void *ptr_arg1: Pointer to the callback function argument1.

void *ptr_arg2: Pointer to the callback function argument2.

struct tag_rs_cellular_http_req

#include <rs_cellular.h>

Structure representing an HTTP request in the cellular module.

Public Members

uint8_t *ptr_data: Pointer to the data for the HTTP request

tx_state_t u8_publish_state: Current state of the HTTP request transmission.

uint32_t u32_read_offset: Offset for reading data.

uint32_t u32_read_len: Length of data to read.

http_req_type_t http_req_type: Type of HTTP request (POST, GET, etc.)

struct tag_rs_http_config

#include <rs_cellular.h>

Structure representing an HTTP configuration in cellular module.

Public Members

uint8_t u8_http_host_name[RS_HTTP_MAX_HOST_NAME_SIZE]: HTTP URL.

uint8_t u8_is_ssl_enable: Flag indicating SSL/TLS encryption status.

uint8_t u8_ssl_id: SSL/TLS ID.

uint8_t u8_ssl_version: SSL/TLS version.

uint8_t u8_ssl_security_level: SSL/TLS security level.

uint8_t u8_content_type: post content type

uint8_t *ptr_request_header: Request header.

struct tag_rs_http_status

#include <rs_cellular.h>

Structure representing an HTTP communication status in cellular module.

Public Members

uint8_t u8_http_connect_status: Status of HTTP connection.

uint32_t u32_http_post_req_count: HTTP post request count.

uint32_t u32_http_get_req_count: HTTP get request count.

uint32_t u32_post_success_count: HTTP Post success count.

uint32_t u32_get_success_count: HTTP get success count.

uint32_t u32_get_failure_count: HTTP get failure count.

uint32_t u32_post_failure_count: HTTP post failure count.

int http_error_code: HTTP error code.

struct tag_rs_cellular_http_instance

#include <rs_cellular.h>

Structure representing an HTTP information in cellular module.

Public Members

uint8_t u8_state: Current state of HTTP module.

rs_handle_t http_handle: Handle of the Cellular HTTP.

rs_http_config_t *ptr_http_config: Pointer to the HTTP config structure.

rs_http_status_t http_status: Pointer to the HTTP status structure.

uint8_t u8_http_connect_request: HTTP connect request.

rs_cellular_http_req_info_t http_post_info: Pointer to the HTTP post info structure.

rs_cellular_http_callback ptr_cb: Pointer to the callback function.

void *ptr_arg1: Pointer to the callback function argument1.

void *ptr_arg2: Pointer to the callback function argument2.

struct tag_cellular_cmd

#include <rs_cellular.h>

Structure representing a cellular command.

Public Members

rs_handle_t handle: Handle for the cellular command.

uint8_t u8_command_id: Command ID.

uint8_t *ptr_cmd: Command string.

uint32_t u32_response_scan_val: Value to scan for in the response.

uint32_t u32_timeout: Timeout value for the command.

struct tag_rs_cellular_instance

#include <rs_cellular.h>

Structure representing cellular instance information.

Public Members

rs_cellular_config_t *ptr_config: Pointer to the configuration structure.

rs_handle_t cellular_serial_handle: Handle of the Cellular Serial.

rs_cellular_status_t cellular_status: Pointer to the cellular status structure.

rs_cellular_module_info_t cellular_info: Pointer to the cellular info structure.

rs_cellular_mqtt_instance_t cellular_mqtt[RS_MAX_MQTT_CONNECTION]: Pointer to the cellular mqtt structure.

rs_cellular_http_instance_t cellular_http[RS_MAX_HTTP_CONNECTION]: Pointer to the cellular http structure.

rs_cellular_gnss_t cellular_gnss: Pointer to the cellular GNSS structure.

uint8_t state: Current cellular State.

uint8_t next_state: Next cellular State.

uint32_t u32_wait_delay_time: Wait Delay Time.

uint32_t u32_current_time: Current time.

uint8_t u8_command_string[RS_CELLULAR_MAX_COMMAND_STRING_SIZE]: parameter command array

cellular_cmd_t cellular_cmd: Pointer to the cellular command structure.

rs_handle_t lock_protocol_handle: Handle of the Cellular lock protocol.

rs_cellular_callback ptr_cb: Pointer to the callback function.

void *ptr_arg: Pointer to the callback function argument.