This topic describes how to get a POSIX/Linux legacy app written in C running on a Legato device and using Legato APIs to access services like SMS, SIM, voice calling, and data connections.

Note: The examples in this topic all use the command-line tools, so you will need to have your shell configured correctly by running bin/legs in the directory in which your framework is installed.
$ path/to/LegatoFramework/bin/legs; These examples assume you are using a Sierra Wireless WP85xx device. If you're using another device, substitute that device wherever you see "WP85" or "wp85".

Cross-Build

The most basic way to get your legacy app running on a Legato target device is to recompile it using the provided cross-build tool chain and copy it onto the device using a tool like scp.

1. Build a legacy app executable for your target device using the cross tool chain provided.

$ $WP85_TOOLCHAIN_DIR/arm-poky-linux-gnueabi-gcc -o legacyProgram main.c

2. Copy the legacy app executable onto the target using a tool like scp:

$ scp legacyProgram 192.168.1.2:
legacyProgram                100% 9366     9.2KB/s   00:00

3. Run the legacy app from the target command-line:

root@swi-mdm9x15:~# ./legacyProgram

Hello world.

Use Legato App Management Tools

By bundling your program as a Legato app, you gain access to a wealth of valuable features:

Tools for installing and removing apps and checking app status on the target and on the development host.
Remote (over-the-air) installation, upgrade, removal, start, stop.
Autonomous fault recovery (automatic restart of process, whole app, or whole device) in the field.
Automatic mandatory access control (MAC) configuration.
Optional application sandboxing.
Optional application signing and/or encryption.

1. Create a .adef file (e.g., legacyProgram.adef) that bundles the cross-compiled executable into an application:

// Disable the sandbox security to make things a little easier.
sandboxed: false
// Put the cross-compiled legacy program in the app's bin directory.
// [x] = make it executable.
bundles:
{
    file:
    {
        [x] legacyProgram /bin/
    }
}
// Tell the Supervisor to start this program when the application is started.
processes:
{
    run:
    {
        ( legacyProgram )
    }
}

2. Run mkapp to generate an application bundle for your target:

$ mkapp -t wp85 legacyProgram.adef

3. Install the app bundle on the target using instapp:

$ instapp legacyProgram.wp85.update
Installing application 'legacyProgram' from file 'legacyProgram.wp85'.
Installing app 'legacyProgram'...
Created user 'applegacyProgram' (uid 1011, gid 1011).
DONE

4. From the target's command line, use app start to run the program:

$ ssh root@192.168.1.2
Linux swi-mdm9x15 3.4.91-8fcd3d08ac_7e84772e18 #1 PREEMPT Wed Jun 3 23:59:46 PDT 2015 armv7l GNU/Linux
root@swi-mdm9x15:~# app start legacyProgram
Starting app 'legacyProgram'...
DONE

5. Look for the program output in the target device's log using logread.

Note: You can filter the log to show just your program's output by piping the output from logread into grep.

root@swi-mdm9x15:~# logread | grep legacyProgram

Jan 16 04:00:53 swi-mdm9x15 user.info Legato: INFO | legacyProgram[27271] | Hello world.

Use Legato Services

Many Legato services are provided through IPC-based APIs. The ifgen tool can generate the IPC code for you, along with a header (.h) file that you can #include to gain access to the service.

Here is how to use a Legato modem service API (e.g., le_info). The source code for this example can be found in apps/sample/legacy/useLegatoApi/.

1. Run ifgen to generate the .c and .h files you need to access the interface.

Use the –gen-interface option to generate the interface header (le_info_interface.h).
Use the –gen-client option to generate the client-side IPC implementation (le_info_client.c).
Use the –gen-local option to generate definitions that are shared by both the client side and server side IPC code (le_info_messages.h).

ifgen --gen-interface --gen-client --gen-local $LEGATO_ROOT/interfaces/modemServices/le_info.api

2. Include legato.h in your program.

#include "legato.h"

3. Include the API's generated "interface" header file.

#include "le_info_interface.h"

4. Connect to the service by calling le_info_ConnectService() (using legacy main function).

int main(int argc, char** argv)
{
    le_info_ConnectService();
    return EXIT_SUCCESS;
}

Note: At runtime, if the le_info service isn't available, this will block until it becomes available. In the meantime, you'll see your app in the WAITING CLIENTS list if you run sdir list.

5. Add a call to one of the le_info API functions (e.g., le_info_GetDeviceModel() ).

int main(int argc, char** argv)
{
    le_info_ConnectService();
    char deviceModelStr[256];
    le_result_t result = le_info_GetDeviceModel(deviceModelStr, sizeof(deviceModelStr));
    if (result == LE_OK)
    {
        printf("Hello world from %s.\n", deviceModelStr);
    }
    else
    {
        printf("Failed to get device model. Error = '%s'.\n", LE_RESULT_TXT(result));
    }
    return EXIT_SUCCESS;
}

Note: For hand-written C code, you need to use \n to terminate messages as stdout only displays info in the buffer after it reaches a new line.

6. Compile and link your executable with the code generated by ifgen:

$ export CC=$WP85_TOOLCHAIN_DIR/arm-poky-linux-gnueabi-gcc
$ $CC -c main.c -I$LEGATO_ROOT/framework/c/inc
$ $CC -c le_info_client.c -I$LEGATO_ROOT/framework/c/inc
$ $CC -o legacyProgram main.o le_info_client.o -L${LEGATO_ROOT}/build/${TARGET}/bin/lib -llegato -lpthread -lrt

7. Specify which instance of the le_info service your app should use by creating a binding in the .adef file:

bindings:
{
     .le_info -> modemService.le_info
}

Note: Actually, there's only one instance of le_info today, but if there were multiple, this would specify which one to use; and even when there's only one instance, we create a binding anyway to explicitly grant access permission so access is never unknowingly granted.

9. Re-generate your application bundle, install it, and run it on target:

$ mkapp -t wp85 legacyProgram.adef
$ instapp legacyProgram.update.wp85 192.168.1.2
Installing application 'legacyProgram' from file 'legacyProgram.wp85'.
Removing app 'legacyProgram'...
Deleted user 'applegacyProgram'.
Installing app 'legacyProgram'...
Created user 'applegacyProgram' (uid 1011, gid 1011).
DONE
$ startapp legacyProgram 192.168.1.2

Callbacks from Legato APIs

If you need asynchronous callbacks (i.e., handlers), you'll need to service the Legato event loop for your thread. To do this, use le_event_GetFd() and le_event_ServiceLoop(). See Integrating with Legacy POSIX Code for more details.

The sample app for this is found in apps/sample/legacy/useLegatoHandler.

Here's some sample code:

struct pollfd pollControl;
pollControl.fd = le_event_GetFd();
pollControl.events = POLLIN;
while (true)
{
    int result = poll(&pollControl, 1, -1);
    if (result > 0)
    {
        while (le_event_ServiceLoop() == LE_OK)
        {
            /* Work was done by le_event_ServiceLoop(), and it has more to do.  */
        }
    }
    else
    {
        // Poll failed.  You could check for zero if you're ultra paranoid,
        // but poll should never return zero when timeout is -1.
        LE_FATAL("poll() failed with errno %m.");
    }
}

Sandboxing Your App

To tell the Supervisor to run your app inside a sandbox, remove the following line from your app's .adef file:

sandboxed: false

Or, you can change false to true:

sandboxed: true

Then re-bundle your app using mkapp.

The most commonly-used system libraries, such as libc and libpthread, will be visible inside your app's sandbox by default, but you may now find that your app won't run because some other files are missing from its sandbox.

Use the requires: section in the app's .adef file to add things to the sandbox.

Sample Legacy Apps

Sample Legacy C apps are available in the Legato/apps/sample/legacy directory.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.