Data Connection

API Reference

A data connection is needed for applications that exchange data with devices where SMS messages are insufficient or not possible. The data connection can be over a mobile network, over Wi-Fi, or over a fixed link (e.g., Ethernet).

The data connection service provides a basic API for requesting and releasing a data connection.

Note
This interface does not support yet data connection over a fixed link.

IPC interfaces binding

All the functions of this API are provided by the dataConnectionService application service.

Here's a code sample binding to Data Connection services: 

bindings:
{
   clientExe.clientComponent.le_data -> dataConnectionService.le_data
}

Default Data Connection

Default data connection is obtained using le_data_Request(). Before the data connection is requested, an application registers a connection state handler using le_data_AddConnectionStateHandler(). Once the data connection is established, the handler will be called indicating it's now connected. If the state of the data connection changes, then the handler will be called with the new state. To release a data connection, an application can use le_data_Release().

The technology of the established connection can be retrieved with le_data_GetTechnology().

If the default data connection is not currently available when le_data_Request() is called, the data connection service first ensures all pre-conditions are satisfied (e.g., modem is registered on the network), before trying to start the data connection.

If the default data connection is already available when le_data_Request() is called, a new connection will not be started. Instead, the existing data connection will be used. This happens if another application also requested the default data connection. This is how multiple applications can share the same data connection.

Once an application makes a data connection request, it should monitor the connection state reported to the registered connection state handler. The application should only try transmitting data when the state is connected, and should stop transmitting data when the state is not connected. If the state is not connected, the data connection service will try to re-establish the connection. There's no need for an application to issue a new connection request.

The default data connection will not necessarily be released when an application calls le_data_Release(). The data connection will be released only after le_data_Release() is called by all applications that previously called le_data_Request().

Note
When using the cellular technology, the data connection service can use a specific cellular data profile if it has been set with the le_data_SetCellularProfileIndex() API or in the configuration tree. Otherwise the default cellular profile is used. The profile in use can be retrieved by le_data_GetCellularProfileIndex(). The profile to use is loaded when the first data connection is initiated. The cellular data profile can be configured by le_mdc APIs or cm data tool.

Data connection routing

Default route

By default, the default route is automatically configured by the data connection service using the modem parameters when the cellular technology is connected. If an application wishes to configure its own default route, it should deactivate it in the data connection service by setting the parameter useDefaultRoute to false in the configuration tree (see Configuration tree): 

$ config set dataConnectionService:/routing/useDefaultRoute false bool
Note
The default route activation status can be retrieved with le_data_GetDefaultRouteStatus().
Warning
The default route activation status is only read at start-up and the change will only be effective after a Legato restart.

A sample code showing how to set the modem default route if it isn't set by the data connection server is presented below: 

//--------------------------------------------------------------------------------------------------
/**
 * Set the modem default route for the mobile data connection
 */
//--------------------------------------------------------------------------------------------------
static void SetMdcDefaultRoute
(
    le_mdc_ProfileRef_t profileRef
)
{
    char ipv4GwAddr[LE_MDC_IPV4_ADDR_MAX_BYTES] = {0};
    char ipv6GwAddr[LE_MDC_IPV6_ADDR_MAX_BYTES] = {0};
    char systemCmd[MAX_SYSTEM_CMD_LENGTH] = {0};
 
    // Get IP gateway for IPv4 or IPv6 connectivity
    if (le_mdc_IsIPv4(profileRef))
    {
        LE_ASSERT_OK(le_mdc_GetIPv4GatewayAddress(profileRef, ipv4GwAddr, sizeof(ipv4GwAddr)));
        snprintf(systemCmd, sizeof(systemCmd), "/sbin/route add default gw %s", ipv4GwAddr);
    }
    else if (le_mdc_IsIPv6(profileRef))
    {
        LE_ASSERT_OK(le_mdc_GetIPv6GatewayAddress(profileRef, ipv6GwAddr, sizeof(ipv6GwAddr)));
        snprintf(systemCmd, sizeof(systemCmd), "/sbin/route -A inet6 add default gw %s",
                                                ipv6GwAddr);
    }
    else
    {
        LE_ERROR("Profile is neither IPv4 nor IPv6!");
        exit(EXIT_FAILURE);
    }
 
    LE_DEBUG("Trying to execute '%s'", systemCmd);
    LE_ASSERT(0 == system(systemCmd));
}

Add or remove a route

Specific routes can be added for the cellular connection with le_data_AddRoute(), which is used to route IP packets to a specific address through the data connection service interface. When the routes are not necessary anymore, they can be removed with le_data_DelRoute(). 

// Add a route to the 8.8.8.8 IP address for the cellular connection
le_data_AddRoute("8.8.8.8");
 
// Remove a route to the 8.8.8.8 IP address for the cellular connection
le_data_DelRoute("8.8.8.8");

Technology rank

The technology to use for the default data connection can be chosen by the applications with an ordered list. If the connection becomes unavailable through a technology, the next one in the list is used for the default data connection. If the connection is also unavailable through the last technology of the list, the first technology will be used again. The default sequence is LE_DATA_WIFI at rank #1 and LE_DATA_CELLULAR at rank #2.

Note
  • Only one list is available and therefore only one application should set the technology preferences for the default data connection.
  • The list should not be modified while the default data connection is established.
  • le_data_SetTechnologyRank() sets the rank of the technology to use for the data connection service. le_data_SetTechnologyRank() inserts a technology into a list, so all the technologies previously set with ranks r and r+n are automatically shifted to ranks r+1 and r+n+1. Technologies with ranks under r are not impacted. If the technology is already in the list, it is removed from its current rank and added to the new rank.
  • le_data_GetFirstUsedTechnology() and le_data_GetNextUsedTechnology() let you retrieve the different technologies of the ordered list to use for the default connection data.

Date and time

When the data connection service is connected, the date and time can be retrieved from a distant server using le_data_GetDate() and le_data_GetTime(). The time protocol and time server to use are configured through the Configuration tree database:

  • Time protocol:
  • Time server: address of the time server to connect to. If not set, the default value is time.nist.gov for LE_DATA_TP and to pool.ntp.org for LE_DATA_NTP.
Note
The configured time protocol needs to be supported by your platform to be used by the data connection service.

Configuration tree

The configuration database of the dataConnectionService allows configuring:

  • the default routing
  • the Wi-Fi access point
  • the cellular profile
  • the time protocol and server.

The configuration is stored under the following path: 

 dataConnectionService:/
     routing/
         useDefaultRoute<bool> == true
     wifi/
         SSID<string> == TestSsid
         secProtocol<int> == 3
         passphrase<string> == Passw0rd
     cellular/
         profileIndex<int> == index
     time/
         protocol<int> == 0
         server<string> == my.time.server.com
Note

Copyright (C) Sierra Wireless Inc.