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 established over a mobile network, WiFi or 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 a data connection over a fixed link.

Warning: The dependency between the cellNetService and dataConnectionService has been removed. A data connection request will no longer ensure that the radio is on, or verify that the SIM is valid and unlocked.

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. The interface name is sent only when the data connection is in connected state. 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 establish or re-establish the connection endlessly until le_data_Release() is called. 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.

Deprecated:: The DCS functionality to populate the default APN name into the cellular channel's modem profile if blank at startup upon an attempt to start it will be deprecated in Legato Release 19.08. After 19.08, DCS will not alter the APN name in any cellular channel's modem profile.

Code sample

A sample code that implements the establishment of a data connection service can be found in dcsTest.c file (please refer to Sample code for data connection service establishment page).

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

Warning: To get the date and time, use GetDateTime rather than sequential calls to GetDate and GetTime to avoid the possibility of a date change between the two calls.

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:
- LE_DATA_TP to use the Time Protocol, defined in RFC 868.
- LE_DATA_NTP to use the Network Time Protocol, defined in RFC 5905.
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

The security protocol is one of the supported protocols defined in the le_wifiClient_SecurityProtocol_t enumerator.
The time protocol is one of the supported protocols defined in the le_data_TimeProtocol_t enumerator.