LPA Utility API

group lpautilities

The Documentation is provided for Network Utility functions used by the LPA application to demonstrate the Low power functionality.

Code Snippets

Code Snippet 1: Using wait_net_suspend for suspend/resume network stack

The following code snippet demonstrates an example for Suspending Network stack to allow MCU to go to Deep Sleep. LPA API cylpa_on_emac_activity should be called to resume network stack in order to queue packets to LwIP.

    /* Configures an emac activity callback to the Wi-Fi interface and
     * suspends the network if the network is inactive for a duration of
     * INACTIVE_WINDOW_MS inside an interval of INACTIVE_INTERVAL_MS. The
     * callback is used to signal the presence/absence of network activity
     * to resume/suspend the network stack.
     */
    void main_task()
    {
        ...
        for (;;)
        {
           wait_net_suspend(wifi, portMAX_DELAY, INACTIVE_INTERVAL_MS, INACTIVE_WINDOW_MS);
           vTaskDelay(pdMS_TO_TICKS(100));
        }
    }
    
    void child_task()
    {
        ...
        /* Call LPA API to resume network stack which is suspended by wait_net_suspend
         * Function. This should be called by any process which wants to send packets to
         * WLAN when network stack is suspended.
         */
        cylpa_on_emac_activity(true);

        /* Call any API to queue packets to LwIP
         */
        ...
    }

Code Snippet 2: Read OLM configuration from device configurator.

The following code snippet demonstrates an example for reading OLM configuration from device configurator and makes a local copy of the list.

        ...
        olm_t *olm_inst = NULL;
        ol_desc_t* dev_cfg_list = NULL;

        olm_inst = cy_get_olm_instance();
        if ( olm_inst != NULL )
        {
            /* make a copy to local list */
            dev_cfg_list = (ol_desc_t *)olm_inst->ol_list;
            ...

Code Snippet 3: Search for TCP KA offload in the device configurator list.

The following code snippet demonstrates an example for searching the “TKO” string in the device configurator list and if not present it add manual TCP KA offload configuration.

        ...
        tmp = cylpa_find_my_descriptor ( "ARP", dev_cfg_list);
        if ( tmp != NULL )
        {
            i++;
        }
        tmp = cylpa_find_my_descriptor ("PKT_Filter", dev_cfg_list );
        if ( tmp != NULL )
        {
            i++;
        }
        tmp = cylpa_find_my_descriptor ( "TKO", dev_cfg_list );
        if ( tmp == NULL )
        {
           /* ADD TKO to list */
           dev_cfg_list = (cy_tko_ol_cfg_t *)tmp->cfg;
           dev_cfg_list[i].name  = "TKO";
           dev_cfg_list[i].cfg   = &tko_new_cfgs[0];
           dev_cfg_list[i].fns   = &tko_ol_fns;
           dev_cfg_list[i].ol    = &tko_ctxt;
        }
        ...

Code Snippet 4: Use cylpa_restart_olm when the OLM configuration is changed by the user application.

The following code snippet demonstrates an example for Restarting OLM interface with user defined configuration.

     ....
     /* disconnect to ap if connnected */

     cylpa_restart_olm(dev_cfg_list, netwk_intf);
     ....

Code Snippet 5: Use cy_tcp_create_socket_connection to offload TCP Keep-alive to WiFi Firmware

The following code snippet demonstrates an example for creating TCP connection(s) and offloads TCP keep-alive when host MCU enters sleep/deepsleep via wait_net_suspend API call.

        ...
        for (int index = 0; index < MAX_TKO; index++)
        {
            /* Establish TCP connection */
            response =  cy_tcp_create_socket_connection(netwk_intf, (void **)&glob_socket[index], remote_ip[index],
                                                        remote_port[index], local_port[index], tko_new_cfgs, tcp_keealive_flag);
            ....

Code Snippet 6: Read OLM configuration from device configurator.

The following code snippet demonstrates an example for reading OLM configuration from device configurator and makes a local copy of the list.

        ...
        void *olm_inst = NULL;
        ol_desc_t* dev_cfg_list = NULL;

        olm_inst = cy_get_olm_instance();
        if ( olm_inst != NULL )
        {
            /* make a copy to local list */
            dev_cfg_list = (ol_desc_t *)get_default_ol_list();
            ...

Functions

int32_t wait_net_suspend(void *net_intf, uint32_t wait_ms, uint32_t inactive_interval_ms, uint32_t inactive_window_ms)

Network Monitor Function.

In this function the network is monitored for inactivity in an interval of length inactive_interval_ms. If the network is inactive for a continuous duration specified by inactive_window_ms, the TCP/IP network stack is suspended and stays suspended until either there is emac activity or a duration of wait_ms has expired. Network stack is resumed on either detecting emac activity or if wait_ms time has elapsed.

Return

int32_t : Returns status on one of these cases: Network error status if the network stack suspension failed or EMAC activity status as a result of network inactivity monitor.

Parameters
  • *net_intf: : pointer to WLAN interface

  • wait_ms: : The interval for which the network is monitored for activity. Network stack is resumed ether at the end of wait_ms or on emac activity.

  • inactive_interval_ms: : The interval for which the network is monitored for inactivity.

  • inactive_window_ms: : The continuous duration for which network has to be inactive in inactive_interval_ms.

void cylpa_on_emac_activity(bool is_tx_activity)

Network Monitor Function.

This function should be used for waking up Network Stack from suspended/lock state. TCPIP Core will locked in wait_net_suspend function for putting MCU to Deep Sleep. Any task which needs to queue to LwIP should be call this function to unlock TCPIP Core.

Return

void

Parameters
  • is_tx_activity: : set event bit for TX/RX activity

int cy_tcp_create_socket_connection(void *net_intf, void **socket_handle, const char *remote_ip, uint16_t remote_port, uint16_t local_port, cy_tko_ol_cfg_t *downloaded, int socket_keepalive_enable)

Creates TCP Socket connection.

This function can be used as reference to create tcp socket connection to provided remote ip address, remote port, local port and the tcp socket handle is returned in *socket_handle

Return

int : Returns CY_RSLT_SUCCESS if the TCP socket connection is successful, otherwise it returns a socket error status

Parameters
  • net_intf: : Pointer to WLAN interface

  • socket_handle: : Pointer to an Array of TCP Socket Handle which is populated by this API

  • remote_ip: : Pointer to Remote TCP IP Address

  • remote_port: : Pointer to Remote TCP IP Port number

  • local_port: : Pointer to Local TCP IP Port number

  • downloaded: : Pointer to TKO offload list

  • socket_keepalive_enable: : Host TCP Keepalive enable 1 or 0 disable.

int cylpa_restart_olm(ol_desc_t *offload_list, void *net_intf)

Restarts OLM.

This function restarts OLM manager with configuration passed by the caller.

note

: This API should only be invoked when device is not connected to AP, if it is connected to an AP then it has to do disconnect first and then invoke this API

Return

int : Returns CY_RSLT_SUCCESS if the restart is successful, otherwise it returns error.

Parameters
  • offload_list: : Pointer to the user defined configuration list ol_desc_t

  • net_intf: : Pointer to WLAN interface

ol_desc_t *cylpa_find_my_descriptor(const char *name, ol_desc_t *offload_list)

Finds OLM descriptor for a given name.

This function finds the OLM descriptor for a given name passed by the caller in a OLM descriptor list.

Return

ol_desc_t : Returns OLM descriptor matching the name, otherwise it returns NULL

Parameters
  • name: : Pointer to the string name of OLM descriptor

  • offload_list: : OLM descriptor list

void *cy_get_olm_instance(void)

Get OLM instance.

This function returns OLM instance

Return

olm_t : Return OLM structure pointer