AWS Cellular Interface on RYZ (rm_cellular_ryz_aws)

Middleware implementing the AWS Cellular API for RYZ cellular modems.

Overview

See AWS documentation for how the Cellular API works: https://www.freertos.org/Documentation/api-ref/cellular/index.html

Features

The following RYZ modems are supported by this port:

• RYZ014A (https://www.renesas.com/us/en/products/interface-connectivity/wireless-communications/cellular-iot-modules/ryz014a-lte-cat-m1-cellular-iot-module)
• RYZ024A (https://www.renesas.com/us/en/products/interface-connectivity/wireless-communications/cellular-iot-modules/ryz024a-lte-cat-m1-cellular-iot-module-global-deployment)

Please see the data sheets for hardware configuration for modems. Some notable differences between the two are:

• RYZ014A default baud is 921600. RYZ024A default baud is 115200.
• RYZ014A reset pin has to be toggled high to reset the modem. RYZ024A is the opposite and has to be toggled low.
• RYZ024A doesn't support AT+CREG. AT+CEREG should be used instead.

All APIs are supported by the RYZ port with the exception of the following RAT APIs:

• Cellular_SetRatPriority
• Cellular_GetRatPriority

The following URCs are supported by the RYZ port:

• CEREG (Cellular_RegisterUrcNetworkRegistrationEventCallback)
• SYSSTART (Cellular_RegisterModemEventCallback)
• SHUTDOWN (Cellular_RegisterModemEventCallback)
• SQNSRING (Cellular_SocketRegisterDataReadyCallback)

Support for other RYZ URCs can be possibly added by request in future releases.

Limitations

• RYZ024A doesn't support AT+CREG. API implementations don't use AT+CREG and use AT+CEREG instead.
• This module does not handle the RYZ reset pin. The user should manually configure this pin in order to reset the module.
• The RYZ can only be used in buffer reception mode, not transparent mode. When calling Cellular_SocketConnect only CELLULAR_ACCESSMODE_BUFFER is supported.
• The AWS Cellular APIs don't currently allow the local port to be set for UDP. It can be set by modifying the localPort field in CellularSocketHandle_t after calling Cellular_CreateSocket but before calling Cellular_SocketConnect.

Configuration

AWS Cellular Interface

Build Time Configurations for source

The following build time configurations are defined in aws/cellular_interface/cellular_config.h:

Configuration	Options	Default	Description
Mobile Country Code Max Size	Value must be a positive integer	3	Mobile country code max size.
Mobile Network Node Max Size	Value must be a positive integer	3	Mobile network code max size.
Integrated Circuit Card Identity Max Size	Value must be a positive integer	20	Integrated circuit card identity max size.
International Mobile Subscriber Identity Max Size	Value must be a positive integer	15	International Mobile Subscriber Identity max size.
Firmware Version Max Size	Value must be a positive integer	32	Cellular module firmware version max size.
Hardware Version Max Size	Value must be a positive integer	12	Cellular module hardware version max size.
Serial Number Max Size	Value must be a positive integer	12	Cellular module serial number max size.
International Mobile Equipment Identity Max Size	Value must be a positive integer	15	International Mobile Equipment Identity number max size.
Registered Network operator Name Max Size	Value must be a positive integer	32	Registered network operator name max size.
Access Point Name Max Size	Value must be a positive integer	64	Access point name max size.
Packet Data Network Username Max Size	Value must be a positive integer	32	Packet data network username max size.
Packet Data Network Password Max Size	Value must be a positive integer	32	Packet data network password max size.
Data Network IP Address Max Size	Value must be a positive integer	40	Cellular data network IP address max size.
AT Command Max Size	Value must be a positive integer	200	Cellular AT command max size.
Max Number of Sockets	Value must be a positive integer	6	Cellular module number of socket max size.
Manufacturer ID Max Size	Value must be a positive integer	20	Cellular module manufacturer ID max size.
Model ID Max Size	Value must be a positive integer	10	Model ID max size.
EDRX List Max Size	Value must be a positive integer	4	EDRX list max size.
PDN Context ID Min Value	Value must be a positive integer	1	PDN context ID min value.
PDN Context ID Max Value	Value must be a positive integer	16	PDN context ID max value.
RAT Priority Count	Value must be a positive integer	3	RAT (radio access technology) priority count.
Socket Max Send Data Length (bytes)	Value must be in the range 1 - 1500	1460	Socket max send data length.
Socket Max Receive Data Length (bytes)	Value must be in the range 1 - 1500	1500	Socket max receive data length.
GetHostByName Support	Enabled (default) Disabled	Enabled (default)	Enables/disable GetHostByName.
Comm Interface Send Timeout (ms)	Value must be a positive integer	1000	Cellular comm interface receive timeout in ms.
Comm Interface Receive Timeout (ms)	Value must be a positive integer	50	Cellular comm interface receive timeout in ms.
Static Allocation Context	Enabled Disabled (default)	Disabled (default)	Use statically allocated context.
Comm Interface Static Allocation Context	Enabled Disabled (default)	Disabled (default)	Use statically allocated context for comm interface.
Default RAT	GSM WCDMA EDGE HSDPA HSUPA HSDPAHSUPA LTE CATM1 NBIOT	CATM1	Default Radio Access Technology.
GSM Support	Enabled Disabled (default)	Disabled (default)	This should be disabled when a modem doesn't support GSM or the AT+CGREG command.
Static Socket Context	Enabled Disabled (default)	Disabled (default)	Use statically allocated socket.
AT Command Timeout (ms)	Value must be a positive integer	5000	Cellular common AT command timeout.
AT Command Raw Timeout (ms)	Value must be a positive integer	5000	Cellular AT command raw timeout.
AT Command Response prefix length	Value must be a positive integer	5000	Cellular AT command response prefix string length.

RYZ Cellular Interface Port

Configurations for Networking > AWS Cellular Interface on RYZ (rm_cellular_ryz_aws)

This module can be added to the Stacks tab via New Stack > Networking > AWS Cellular Interface on RYZ (rm_cellular_ryz_aws).

Configuration	Options	Default	Description
Module Reset Pin (Port Number)	Refer to the RA Configuration tool for available options.	00	Specify the reset control port for the RYZ module. This property is only used in devassist.
Module Reset Pin (Pin Number)	Refer to the RA Configuration tool for available options.	00	Specify the reset control pin for the RYZ module. This property is only used in devassist.

Examples

Basic Example

void rm_cellular_ryz_aws_basic_example (void)
{
    CellularHandle_t        cellular_handle = NULL;
    CellularSimCardStatus_t sim_card_status;

    /* Initialize Cellular Modem. */
    CellularError_t err = Cellular_Init(&cellular_handle, &g_cellular_comm_interface_on_uart);
    assert(CELLULAR_SUCCESS == err);

    /* Get the SIM card status */
    err = Cellular_GetSimCardStatus(cellular_handle, &sim_card_status);
    assert(CELLULAR_SUCCESS == err);
    assert(CELLULAR_SIM_CARD_INSERTED == sim_card_status.simCardState);
}

Socket Example

#define SOCKET_EXAMPLE_BUFFER_SIZE    (256)
#define SOCKET_EXAMPLE_TIMEOUT        (UINT32_MAX)
#define SOCKET_EXAMPLE_IP             ("255.255.255.255")
#define SOCKET_EXAMPLE_PORT           (80)

uint32_t g_recv_event_count = 0;

void socket_example_data_ready_callback (CellularSocketHandle_t socketHandle, void * pCallbackContext)
{
    FSP_PARAMETER_NOT_USED(socketHandle);
    FSP_PARAMETER_NOT_USED(pCallbackContext);

    g_recv_event_count++;
}

void rm_cellular_ryz_aws_socket_example (void)
{
    CellularHandle_t        cellular_handle = NULL;
    char                  * p_data          = "hello_world";
    char                    recv_buffer[SOCKET_EXAMPLE_BUFFER_SIZE] = "\0";
    uint32_t                sent_data_length     = 0;
    uint32_t                received_data_length = 0;
    uint32_t                timeout_ms           = SOCKET_EXAMPLE_TIMEOUT;
    CellularSocketHandle_t  socket_handle;
    CellularSocketAddress_t socket_address =
    {
        .ipAddress =
        {
            CELLULAR_IP_ADDRESS_V4,
            SOCKET_EXAMPLE_IP
        },
        .port      = SOCKET_EXAMPLE_PORT
    };

    /* Initialize Cellular Modem. */
    CellularError_t err = Cellular_Init(&cellular_handle, &g_cellular_comm_interface_on_uart);
    assert(CELLULAR_SUCCESS == err);

    /* Create a TCP socket */
    err = Cellular_CreateSocket(cellular_handle,
                                1,
                                CELLULAR_SOCKET_DOMAIN_AF_INET,
                                CELLULAR_SOCKET_TYPE_STREAM,
                                CELLULAR_SOCKET_PROTOCOL_TCP,
                                &socket_handle);
    assert(CELLULAR_SUCCESS == err);

    /* Register the data ready callback */
    err = Cellular_SocketRegisterDataReadyCallback(cellular_handle,
                                                   socket_handle,
                                                   socket_example_data_ready_callback,
                                                   NULL);
    assert(CELLULAR_SUCCESS == err);

    g_recv_event_count = 0;

    /* Connect the TCP socket */
    err = Cellular_SocketConnect(cellular_handle, socket_handle, CELLULAR_ACCESSMODE_BUFFER, &socket_address);
    assert(CELLULAR_SUCCESS == err);

    /* Send data over the socket */
    err = Cellular_SocketSend(cellular_handle, socket_handle, (uint8_t *) p_data, strlen(p_data), &sent_data_length);
    assert(CELLULAR_SUCCESS == err);
    assert(strlen(p_data) == sent_data_length);

    /* Wait for data ready callback */
    timeout_ms = SOCKET_EXAMPLE_TIMEOUT;
    while (timeout_ms > 0)
    {
        if (g_recv_event_count > 0)
        {
            break;
        }

        R_BSP_SoftwareDelay(1, BSP_DELAY_UNITS_MILLISECONDS);
        timeout_ms--;
    }

    assert(0 != timeout_ms);

    /* Receive data back */
    err = Cellular_SocketRecv(cellular_handle,
                              socket_handle,
                              (uint8_t *) recv_buffer,
                              SOCKET_EXAMPLE_BUFFER_SIZE,
                              &received_data_length);
    assert(CELLULAR_SUCCESS == err);

    /* Close the socket */
    err = Cellular_SocketClose(cellular_handle, socket_handle);
    assert(CELLULAR_SUCCESS == err);
}

Setting UDP local port

#define UDP_EXAMPLE_IP             ("255.255.255.255")
#define UDP_EXAMPLE_REMOTE_PORT    (80)
#define UDP_EXAMPLE_LOCAL_PORT     (5000)

void rm_cellular_ryz_aws_udp_local_port_set_example (void)
{
    CellularHandle_t        cellular_handle = NULL;
    CellularSocketHandle_t  socket_handle   = NULL;
    CellularSocketAddress_t socket_address  =
    {
        .ipAddress =
        {
            CELLULAR_IP_ADDRESS_V4,
            UDP_EXAMPLE_IP
        },
        .port      = UDP_EXAMPLE_REMOTE_PORT
    };

    /* Initialize Cellular Modem. */
    CellularError_t err = Cellular_Init(&cellular_handle, &g_cellular_comm_interface_on_uart);
    assert(CELLULAR_SUCCESS == err);

    /* Create a UDP socket */
    err = Cellular_CreateSocket(cellular_handle,
                                1,
                                CELLULAR_SOCKET_DOMAIN_AF_INET,
                                CELLULAR_SOCKET_TYPE_DGRAM,
                                CELLULAR_SOCKET_PROTOCOL_UDP,
                                &socket_handle);
    assert(CELLULAR_SUCCESS == err);

    /* Set the local port */
    socket_handle->localPort = UDP_EXAMPLE_LOCAL_PORT;

    /* Connect the UDP socket */
    err = Cellular_SocketConnect(cellular_handle, socket_handle, CELLULAR_ACCESSMODE_BUFFER, &socket_address);
    assert(CELLULAR_SUCCESS == err);
}