Legato Reference Manual - Linkwave - M2M...

Reference Manual Release 16.01.2

Important Notice

Due to the nature of wireless communications, transmission and reception of data can never be guaranteed. Data

may be delayed, corrupted (i.e., have errors) or be totally lost. Although significant delays or losses of data are rare

when wireless devices such as the Sierra Wireless modem are used in a normal manner with a well-constructed

network, the Sierra Wireless modem should not be used in situations where failure to transmit or receive data could

result in damage of any kind to the user or any other party, including but not limited to personal injury, death, or loss

of property. Sierra Wireless accepts no responsibility for damages of any kind resulting from delays or errors in data

transmitted or received using the Sierra Wireless modem, or for failure of the Sierra Wireless modem to transmit or

receive such data.

Safety and Hazards

Do not operate the Sierra Wireless modem in areas where cellular modems are not advised without proper device

certifications. These areas include environments where cellular radio can interfere such as explosive atmospheres,

medical equipment, or any other equipment which may be susceptible to any form of radio interference. The Sierra

Wireless modem can transmit signals that could interfere with this equipment. Do not operate the Sierra Wireless

modem in any aircraft, whether the aircraft is on the ground or in flight. In aircraft, the Sierra Wireless modem MUST

BE POWERED OFF. When operating, the Sierra Wireless modem can transmit signals that could interfere with

various onboard systems.

The driver or operator of any vehicle should not operate the Sierra Wireless modem while in control of a vehicle.

Doing so will detract from the driver or operators control and operation of that vehicle. In some states and provinces,

operating such communications devices while in control of a vehicle is an offence.

Limitations of Liability

This manual is provided as is. Sierra Wireless makes no warranties of any kind, either expressed or implied,

including any implied warranties of merchantability, fitness for a particular purpose, or noninfringement. The recipient

of the manual shall endorse all risks arising from its use.

The information in this manual is subject to change without notice and does not represent a commitment on the part

of Sierra Wireless. SIERRA WIRELESS AND ITS AFFILIATES SPECIFICALLY DISCLAIM LIABILITY FOR ANY

AND ALL DIRECT, INDIRECT, SPECIAL, GENERAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR

EXEMPLARY DAMAGES INCLUDING, BUT NOT LIMITED TO, LOSS OF PROFITS OR REVENUE OR

ANTICIPATED PROFITS OR REVENUE ARISING OUT OF THE USE OR INABILITY TO USE ANY SIERRA

WIRELESS PRODUCT, EVEN IF SIERRA WIRELESS AND/OR ITS AFFILIATES HAS BEEN ADVISED OF THE

POSSIBILITY OF SUCH DAMAGES OR THEY ARE FORESEEABLE OR FOR CLAIMS BY ANY THIRD PARTY.

Notwithstanding the foregoing, in no event shall Sierra Wireless and/or its affiliates aggregate liability arising under or

in connection with the Sierra Wireless product, regardless of the number of events, occurrences, or claims giving rise

to liability, be in excess of the price paid by the purchaser for the Sierra Wireless product.

Customer understands that Sierra Wireless is not providing cellular or GPS (including A-GPS) services. These

services are provided by a third party and should be purchased directly by the Customer.

SPECIFIC DISCLAIMERS OF LIABILITY: CUSTOMER RECOGNIZES AND ACKNOWLEDGES SIERRA

WIRELESS IS NOT RESPONSIBLE FOR AND SHALL NOT BE HELD LIABLE FOR ANY DEFECT OR

DEFICIENCY OF ANY KIND OF CELLULAR OR GPS (INCLUDING A-GPS) SERVICES.

Patents

This product may contain technology developed by or for Sierra Wireless Inc.

This product includes technology licensed from QUALCOMM.

This product is manufactured or sold by Sierra Wireless Inc. or its affiliates under one or more patents licensed from

InterDigital Group and MMP Portfolio Licensing.

Copyright

2016 Sierra Wireless. All rights reserved.

Trademarks

Legato is a trademark of Sierra Wireless.

mangOH is a trademark of Sierra Wireless.

Sierra Wireless, AirPrime

, AirLink

, AirVantage

, WISMO

and the Sierra Wireless and Open AT logos are

registered trademarks of Sierra Wireless, Inc. or one of its subsidiaries.

Watcher is a registered trademark of Netgear, Inc., used under license.

Windows and Windows Vista

are registered trademarks of Microsoft Corporation.

Macintosh and Mac OS X

are registered trademarks of Apple Inc., registered in the U.S. and other countries.

QUALCOMM is a registered trademark of QUALCOMM Incorporated. Used under license.

Other trademarks are the property of their respective owners.

DOCUMENT HISTORY

Version Date Description

15.05.Beta June 15, 2015 initial 15.05 version: Doc ID #4134305

June 24, 2015 corrected code sample - Basics - Create cdef

15.08.Beta August 31, 2015 15.08 version

15.10 Beta November 13, 2015 15.10 version

16.01.2 February 23, 2016 16.01.2 version

Contents

Legato Reference Manual Page i

Contents About...................................................................................................................... 9

Glossary ............................................................................................................ 9 Versions........................................................................................................... 12

Build Apps ............................................................................................................ 13

Learn ................................................................................................................. 14

Basics .............................................................................................................. 14 Runtime Architecture ....................................................................................... 15 Security............................................................................................................ 17 Sandboxes ....................................................................................................... 17 SMACK ............................................................................................................ 18 Components .................................................................................................... 18 Interfaces ......................................................................................................... 20 Configuration ................................................................................................... 21 Event-driven Programming .............................................................................. 22 Power Management ......................................................................................... 23 Inter-process Communication .......................................................................... 24 Internationalization ........................................................................................... 25 Logging ............................................................................................................ 25 LWM2M Data ................................................................................................... 25 Updates ........................................................................................................... 25

Build Apps ......................................................................................................... 27

Create Apps ..................................................................................................... 27 Use IPC ........................................................................................................... 28 Client/Server .................................................................................................... 32 Add Things ...................................................................................................... 33 Deploy Multiple Components ........................................................................... 34

C Language Standards...................................................................................... 34

Commenting .................................................................................................... 34 Const Pointers ................................................................................................. 37 Cyclomatic Complexity..................................................................................... 37 Existing Code .................................................................................................. 37 Extern .............................................................................................................. 37 Fan Out............................................................................................................ 38 Function Parameters ....................................................................................... 38 Global Variables .............................................................................................. 38 Gotos ............................................................................................................... 39 Heap ................................................................................................................ 39 Interface Documentation .................................................................................. 39 Line Length ...................................................................................................... 39 Multiple Inclusion Guards ................................................................................. 39 Multithreading .................................................................................................. 40 Recursion ........................................................................................................ 40 Separating Interface from Implementation ....................................................... 41 Tabs ................................................................................................................ 41 Naming Standards ........................................................................................... 41

Contents

Legato Reference Manual Page ii

Abbreviations ................................................................................................... 46

How To................................................................................................................. 48

Configure Security ............................................................................................. 48

Config Sandbox ................................................................................................. 48

Implementing SMACK ....................................................................................... 49

Customize Legato Yocto USB ........................................................................... 52

Manage Config Tree .......................................................................................... 56

Import/Export Config Trees .............................................................................. 56 Config Tree Transactions ................................................................................. 57 Config Tree Schema ........................................................................................ 59 IPC Binding Configuration Data ....................................................................... 60

Manage GNSS .................................................................................................. 61

Manage Device Power ...................................................................................... 62

Wakeup Sources ............................................................................................. 63 Wakeup & Deferrable Events ........................................................................... 63 Power Manager Clients.................................................................................... 65

NMEA Port Setup .............................................................................................. 66

Port Legacy Apps .............................................................................................. 67

Port Legacy C App ............................................................................................ 69

Set User Timebase ............................................................................................ 75

Troubleshooting ................................................................................................. 76

Use AirVantage ................................................................................................. 77

Connect to AirVantage ..................................................................................... 78 Install apps ...................................................................................................... 79 Manage AirVantage Data ................................................................................. 80

Use Logs ........................................................................................................... 80

Use Software Update ........................................................................................ 81

Definition Files ..................................................................................................... 85 Overview .......................................................................................................... 85 Common File Format ....................................................................................... 87

Application Definition .adef ................................................................................ 90

bindings ........................................................................................................... 90 bundles ............................................................................................................ 91 cpu share ......................................................................................................... 92 executables ..................................................................................................... 93 groups ............................................................................................................. 94 max file system bytes ...................................................................................... 94 max memory bytes .......................................................................................... 94 max mqueue bytes .......................................................................................... 95 max queued signals ......................................................................................... 95 max threads ..................................................................................................... 95 max secure storage bytes ................................................................................ 95 pools ................................................................................................................ 95 processes ........................................................................................................ 96 run ................................................................................................................... 97

Contents

Legato Reference Manual Page iii

env vars ........................................................................................................... 98 fault action ....................................................................................................... 98 priority .............................................................................................................. 98 max core dump file bytes ................................................................................. 99 max file bytes ................................................................................................... 99 max locked memory bytes ..............................................................................100 watchdog action ..............................................................................................100 watchdog timeout ............................................................................................100 extern .............................................................................................................100 server-side example .......................................................................................101 client-side example .........................................................................................101 requires...........................................................................................................102 config tree .......................................................................................................102 dir ...................................................................................................................102 file ...................................................................................................................103 device .............................................................................................................105 sandboxed ......................................................................................................106 start ................................................................................................................106 version ............................................................................................................107 watchdog action ..............................................................................................107 watchdog timeout ............................................................................................107

Component Definition .cdef ............................................................................. 107

assets .............................................................................................................107 bundles ...........................................................................................................108 c flags .............................................................................................................110 c++ flags .........................................................................................................110 linker flags ......................................................................................................110 pools ...............................................................................................................111 provides ..........................................................................................................111 API ..................................................................................................................111

System Definition .sdef .................................................................................... 112

apps ................................................................................................................112 Max Priority .....................................................................................................113 Preloaded .......................................................................................................113 bindings ..........................................................................................................114 commands ......................................................................................................115

API Files............................................................................................................. 116

Contents

Legato Reference Manual Page iv

API Guides ......................................................................................................... 128

Services APIs .................................................................................................. 128

Overview .........................................................................................................129 AirVantage ......................................................................................................130 Audio ..............................................................................................................131 Cellular Network .............................................................................................137 Config Tree .....................................................................................................138 Data Connection .............................................................................................145 GPIO ..............................................................................................................147 Modem............................................................................................................150 Positioning ......................................................................................................202 Power .............................................................................................................207 Secure Storage ...............................................................................................210 SMS Messaging..............................................................................................211 Supervisor ......................................................................................................222 Update ............................................................................................................225 Voice Call Service ...........................................................................................231

C Runtime Library ........................................................................................... 232

Basic Type and Constant Definitions ..............................................................234 Command Line Arguments API.......................................................................235 Directory API ..................................................................................................238 Doubly Linked List API ....................................................................................239 Dynamic Memory Allocation API .....................................................................242 Event Loop API ...............................................................................................248 File Descriptor Monitor API .............................................................................256 File Locking API ..............................................................................................261 HashMap API .................................................................................................263 Hex string API .................................................................................................266 JSON Parsing API ..........................................................................................266 Legato Build Configuration ..............................................................................268 Logging API ....................................................................................................269 Low-Level Messaging API ..............................................................................274 Mutex API .......................................................................................................287 Path API .........................................................................................................288 Path Iterator API .............................................................................................289 Print APIs ........................................................................................................291 Safe References API ......................................................................................291 Semaphore API ..............................................................................................294 Signals API .....................................................................................................295 Singly Linked List API .....................................................................................298 System Clock API ...........................................................................................301 Thread Control API .........................................................................................302 Timer API ........................................................................................................304 Unit Testing API ..............................................................................................306 UTF-8 String Handling API .............................................................................309

Contents

Legato Reference Manual Page v

Tools .................................................................................................................. 311 app .................................................................................................................311 cm ...................................................................................................................312 config ..............................................................................................................317 configEcm .......................................................................................................320 execInApp .......................................................................................................321 fwupdate .........................................................................................................322 inspect ............................................................................................................322 legato ..............................................................................................................323 log ...................................................................................................................324 sdir ..................................................................................................................326 setNet .............................................................................................................326 update ............................................................................................................327

Host ................................................................................................................. 328

av-pack ...........................................................................................................329 configtargetssh ...............................................................................................330 createsdk ........................................................................................................330 fwupdate .........................................................................................................331 gettargettype ...................................................................................................331 instapp ............................................................................................................331 instlegato ........................................................................................................332 instsys.............................................................................................................332 legato-qemu ....................................................................................................333 lsapp ...............................................................................................................333 mklegatoimg ...................................................................................................334 releaselegato ..................................................................................................334 rmapp .............................................................................................................335 security-pack ..................................................................................................335 setname ..........................................................................................................335 settime ............................................................................................................336 simu ................................................................................................................337 startapp...........................................................................................................338 startlegato .......................................................................................................338 statapp ............................................................................................................339 stopapp ...........................................................................................................339 stoplegato .......................................................................................................340 update ............................................................................................................340 update-pack ....................................................................................................341

Build ................................................................................................................ 342

mkapp .............................................................................................................343 mksys .............................................................................................................343 mkexe .............................................................................................................344 mkcomp ..........................................................................................................344 ifgen ................................................................................................................345

Contents

Legato Reference Manual Page vi

Build Platform..................................................................................................... 346

Platform Constraints ........................................................................................ 346

Audio ..............................................................................................................346 Secure Storage ...............................................................................................347

Yocto Info ........................................................................................................ 348

Yocto Legato Builds ........................................................................................348 Yocto Install Notes ..........................................................................................351

Sample Code ..................................................................................................... 353

Audio settings for a dialing call ........................................................................ 353

DTMF playback and decoding ......................................................................... 364

Audio playback and capture ............................................................................ 371

eCall test session with a local voice prompt .................................................... 390

eCall test session with a voice call connection ................................................ 396

Modem Call control ......................................................................................... 402

SMS Cell Broadcast reception ......................................................................... 407

File Documentation ............................................................................................ 418

appSmack_interface.h File Reference ............................................................ 418

le_adc_interface.h File Reference ................................................................... 421

le_antenna_interface.h File Reference ............................................................ 423

le_appInfo_interface.h File Reference ............................................................. 430

le_args.h File Reference ................................................................................. 433

le_audio_interface.h File Reference ................................................................ 441

le_avc_interface.h File Reference ................................................................... 468

le_avdata_interface.h File Reference .............................................................. 475

le_basics.h File Reference .............................................................................. 483

le_bootReason_interface.h File Reference ..................................................... 488

le_build_config.h File Reference ..................................................................... 490

le_cellnet_interface.h File Reference .............................................................. 491

le_cfg_interface.h File Reference .................................................................... 494

le_cfgAdmin_interface.h File Reference .......................................................... 510

le_clock.h File Reference ................................................................................ 514

le_data_interface.h File Reference .................................................................. 519

le_dir.h File Reference .................................................................................... 522

le_doublyLinkedList.h File Reference .............................................................. 524

le_ecall_interface.h File Reference ................................................................. 531

le_eventLoop.h File Reference ........................................................................ 553

le_fdMonitor.h File Reference ......................................................................... 560

le_fileLock.h File Reference ............................................................................ 565

le_fwupdate_interface.h File Reference .......................................................... 572

le_gnss_interface.h File Reference ................................................................. 575

Contents

Legato Reference Manual Page vii

le_gpio_interface.h File Reference .................................................................. 591

le_hashmap.h File Reference .......................................................................... 597

le_hex.h File Reference................................................................................... 608

le_info_interface.h File Reference ................................................................... 610

le_instStat_interface.h File Reference ............................................................. 620

le_ips_interface.h File Reference .................................................................... 623

le_json.h File Reference .................................................................................. 627

le_limit_interface.h File Reference .................................................................. 633

le_log.h File Reference.................................................................................... 634

le_mcc_interface.h File Reference .................................................................. 641

le_mdc_interface.h File Reference .................................................................. 651

le_mdmDefs_interface.h File Reference ......................................................... 673

le_mem.h File Reference ................................................................................ 674

le_messaging.h File Reference ....................................................................... 682

le_mrc_interface.h File Reference ................................................................... 700

le_mutex.h File Reference ............................................................................... 731

le_path.h File Reference ................................................................................. 734

le_pathIter.h File Reference ............................................................................ 737

le_pm_interface.h File Reference .................................................................... 744

le_pos_interface.h File Reference ................................................................... 747

le_posCtrl_interface.h File Reference ............................................................. 758

le_print.h File Reference ................................................................................. 760

le_riPin_interface.h File Reference ................................................................. 762

le_rtc_interface.h File Reference ..................................................................... 764

le_safeRef.h File Reference ............................................................................ 766

le_secStore_interface.h File Reference .......................................................... 770

le_semaphore.h File Reference ...................................................................... 773

le_signals.h File Reference ............................................................................. 776

le_sim_interface.h File Reference ................................................................... 778

le_singlyLinkedList.h File Reference ............................................................... 792

le_sms_interface.h File Reference .................................................................. 797

le_smsInbox1_interface.h File Reference ....................................................... 826

le_sup_ctrl_interface.h File Reference ............................................................ 834

le_sup_wdog_interface.h File Reference ........................................................ 836

le_temp_interface.h File Reference ................................................................. 837

le_test.h File Reference................................................................................... 842

le_thread.h File Reference .............................................................................. 844

le_timer.h File Reference ................................................................................ 853

le_ulpm_interface.h File Reference ................................................................. 859

le_update_interface.h File Reference .............................................................. 862

le_updateCtrl_interface.h File Reference ........................................................ 867

Contents

Legato Reference Manual Page viii

le_utf8.h File Reference .................................................................................. 869

le_voicecall_interface.h File Reference ........................................................... 874

le_wdog_interface.h File Reference ................................................................ 880

legato.h File Reference ................................................................................... 882

logFd_interface.h File Reference .................................................................... 884

secStoreAdmin_interface.h File Reference ..................................................... 886

About - Learn

Legato Reference Manual Page 9

ABOUT This section contains info about this Legato release and build number, and info on how to use the Legato docs.

Legato 16.01.0.Beta (1dd67c4)

Get help or report an issue: Legato Forum

Versions

Legato's goal is to simplify IoT development. We're hoping you'll find the dev environment and app framework so easy to use, you won't need the docs too much.

We have a less is more approach to docs' conventions. We abbreviate, use contractions, and focus on key words. Our formatting is clean and simple. Our language is informal and direct.

Glossary

These are some common terms we use in Legato.

Term (aka) Definition

adef application definition file used to define the external interfaces and internal content of apps that can be built, installed, and run on target devices

AirVantage Sierra Wireless cloud

Application (app) a collection of one or more processes running one or more executables

Application core application processor, usually embedded inside the same chip set as a cellular modem

API Application Programming Interface - set of routines, protocols, and tools for building software applications

.api API file extension

AT see Open At

Beidou Chinese GNSS

BSP Board Support Package

Build Environment Legato's application framework

Build Tools pre-built scripts, executuables, etc to build Legato

C language the C programming language

Runtime Library Legato C Runtime Library

https://forum.sierrawireless.com/viewforum.php?f=177&sid=428b0e9e398a6e02c5f31b4b1a8ec92a

About - Learn



cdef Component definition file used to define the external interfaces and internal content of reusable software components

CDC Communication Device Class specification

CDMA Code Division Multiple Access - channel access method used by radio communication technologies

CID Packet Data Protocol (PDP) Context Identifier

CLIP/CLIR Calling Line Identification Presentation/Restriction

Component collection of code and other files that are functionally related for reuse and sharing

Config Tree device configuration database

Definition Files (def files)

define system, application, and component files used as input to build tools

Device (target) modem, GPS, dev kit or any other hardware

Dev Kit Board Sierra Wireless' developer hardware

Developer Studio Sierra Wireless Windows-based IDE

DTMF dual-tone multi-frequency signaling

event-driven programming where flow is determined by events like sensor outputs

ECM Ethernet Control Modem (subclass of CDC)

Firmware (fw) permanent software programmed into read-only memory

Framework (a-f) software framework used to implement a standardized code structure

Galileo European Union's GNSS

Gateway a node (router) on a TCP/IP network that serves as an access point to another network

Git distributed revision control and source code management system

GitHub web-based hosting service for Git repositories

GLONASS Russian GNSS

GNSS Global Navigation Satellite System, generic name for systems like GPS

GPIO General Purpose Input/Output, a generic pin on a chip

GPRS General packet radio service, a packet oriented mobile data service

GPS Global Positioning System, satellite navigation system

Host omputer that hosts Legato development: the dev host

IDE Integrated Development Environment

Interface software to communicate between devices or programs, or computers and users

IMEI International Mobile Equipment Identity, a number to identify 3GPP devices

About - Learn



IPC inter-process communication

Kernel Core of an operating system (hardware abstraction, security, and software abstraction)

language independent Legato's interface definition language (IDL), similar to C, renamed to API Files

le_* C runtime library source files

MAC Media Access control - MAC address

MSD Minimum Set of Data

Modem Integrated telecom processor or external modem

NMEA National Marine Electronics Association used to communicate between marine navigation and control devices

Open AT Sierra Wireless application framework and operating system for M2M communication

PLMN Public Land Mobile Network

Process virutal memory address space executing one or more threads

Root File System file system contained on the same partition on which the root directory is located

Runtime Environment a standardized configuration for environment variables

Sandbox security mechanism for separating running programs

sdef system definition files are use to interconnect apps with each other and with the target's runtime environment (e.g., hardware devices)

Service ready to use IPC APIs

Source Sierra Wireless resource hub

Supervisor privileged process running on the target

SSH Secure Shell

smack utility to spoof MAC address

stack hardware register that holds the address of a memory location

TAIP Trimble ASCII Interface Protocol, common for vehicle monitoring

Target (device) an embedded wireless module

thread thread of execution - sequence of prgrammed instructions

Tools Target, Host, and Build tools

Toolchain development toolset linked (or chained) together

xdef all definition files: adef, cdef, sdef

Yocto Yocto open source project for BSPs

About - Learn


Versions

Previously released versions of the Legato online help are stored on GitHub in the related directory.

The default version accessed from Legato.io is the most recent Legato docs.

To access previous versions:

o you can search Google (e.g., "Legato 15.10")

o you can enter the version number in the URL (e.g., change http://www.legato.io/legato-

docs/16_01 / to http://www.legato.io/legato-docs/15_10 /).

Build Apps - Learn


BUILD APPS

Welcome

Legato is an open source embedded platform built on Linux designed to simplify embedded IoT

development.

Overview

Legato has everything you need to connect the IoT fast:

Programming language APIs dev tools and APIs to easily write software components and specify how apps will use them.

Target runtime environment set of daemon processes cooperatively implement execution sandboxes, secure IPC, fault monitoring.

Development and build tools target, host, and build tools to create apps ready for deployment to your devices.

Documentation and automated tests a raft of docs and automated tests ready to use.

Get Started

Documentation

Legato is an open source embedded platform built on Linux designed to simplify embedded IoT

development.

This is how the docs are organized:

Section Description

Learn essentials to get developing

API Guides pre-built services and C language library

Tools target, host and build tools

The Legato online docs are also available in a PDF doc.

Build Apps - Learn


Learn

Section Description

Basics essentials to get developing

How To frequently needed tasks

Definition Files reusable external interfaces & internal content

API Files language-independent interfaces

Basics

This section contains the essential basics to understand how Legato works including key development info and details on Legato's sample apps.

Concepts

Build Apps

C Language Standards

Concepts

Runtime Architecture

Security

Components

Interfaces

Configuration

Event-driven Programming

Power Management

Inter-process Communication

Internationalization

Logging

LWM2M Data

Updates

Glossary

Build Apps - Learn


Overview

Legato is designed to make developing component-based software for embedded devices in the Internet-of-things (IoT) easier, faster, and less expensive.

Runtime Architecture

Legato's runtime architecture manages each app in its own sandbox.

Build Apps - Learn


Apps communicate with each other using access-controlled message-passing services.

The Supervisor automatically creates sandboxes.

Applications

An application (we call them 'apps') is a collection of executable files, libraries, and/or other resource files (e.g., audio files, web pages) that can be deployed to a target device. Once installed on a device, an app can be started and stopped.

By default, each app runs in its own sandbox. When an app is constructed, all the files and IPC services it needs to access are declared. At runtime, the Supervisor and the Service Directory enforce that only approved files and IPC services are accessed by that app.

Create Apps

Supervisor

The Supervisor is a privileged process running on the target device that:

o creates and destroys Sandboxes for apps

o starts and stops apps

o performs fault recovery when apps fail (e.g., restarting the app).

Service Directory

Legato's Service Directory provides a secure way for client processes to find servers offering services they need, which ensures only authorized connections are established.

Services APIs

Interfaces

Config Tree

The Config Tree provides persistent Configuration data storage organized in a tree structure.

Command line config tool

Config Tree API

Watchdog

Legato kickable watchdog service provides a timeout that can be configured in defFilesAdef or

specified at run time. If a kick is not received in the specified time, the supervisor signals to perform the action specified in Watchdog Action.

Watchdog Service

Application Definition .adef

Logs

Legato provides a user-friendly way to control log message filtering for running app processes.

Command line log tool

Build Apps - Learn


Logging API.

Update Daemon

The Update Daemon accepts update pack files that contain software/firmware update instructions and associated data like libraries, executables, and resource files.

Update packs can be fed to the Update Daemon through the Software Update API or through the update tool.

The Update Daemon includes hooks that allow update packs to be digitally signed and/or encrypted for security reasons.

Security

Sandboxes

SMACK

Sandboxes

Also see Config Sandbox

Legato uses sandboxes to provide a security layer against untrusted apps running in the same system. Legato sandboxes isolate apps from the rest of the system. This allows both original equipment manufacturers (OEM) and independent software vendors (ISV) components to safely coexist on the same device without fear of interfering or breaking the stack.

Access control for files is done using the underlying POSIX access control mechanisms, based on users, permissions, and SMACK labels.

All sandboxes are created in RAM, which provides the benefit of automatically removing all sandboxes during system shutdown. Legato sandboxes use bind mounts to import files into

sandboxes (defined using the .adef and .sdef requires section). Bind-mounted files are updated

when the file is updated. Bind-mounted files aren't copied so memory requirements are minimal.

A Legato sandboxed app can access services outside its sandbox. All available services are advertised by the Service Directory. Apps connect to services through a request to the Service Directory. The Service Directory grants access only if the app has been explicitly bound to a service

(using the .adef and .sdef bindings section).

Legato sandboxes use chroot to limit an app's view to its own file system only. Each app has its own unique user ID, group ID, and root directory. Files are bound into the chroot jail using bind mounts that change a process's root directory to a specified location. The process then only has access to files and directories under its root directory. Only processes with certain capabilities can find their way outside of their root directory.

Legato sandboxes also provide resource limitations . Resource limitations place limits on the amount of system resources an app is allowed to consume. Without resource limits, an isolated app can still cause damage by consuming all available resources.

Build Apps - Learn


SMACK

Simplified Mandatory Access Control Kernel (SMACK) provides a simple solution for mandatory access control (MAC). MAC provides the ability for a centralized entity to set access policy for system resources.

The Linux default access control policy is governed by permission bits on system resources at the discretion of the resource owner: discretionary access control (DAC). Policies are set in a distributed way so different system users can set access policy for their own resources.

MAC policies are often used to overcome DAC limitations for systems that require a higher level of security.

SMACK is used to supplement DAC. DAC permissions are checked first; if access is granted, SMACK permissions are then checked. SMACK can only limit access, it can't grant access beyond DAC permissions.

SMACK uses 'labels' on resources (objects in SMACK terminology) and processes (subjects) to determine access. Labels on resources can only be set by a privileged process (the

CAP_MAC_OVERRIDE label designates a process as privileged )

SMACK policies are set by the Legato startup scripts, the Legato Installer and the Legato Supervisor.

Here's Implementing SMACK.

Components

In Legato, a component is a collection of code and other files that are functionally related, along with one or more licenses that apply to the components' files.

Components can be "built" generating output like object code libraries and other files. These files can be incorporated into applications and run on a target device.

Legato components can also have language-independent interfaces and configuration data.

Rationale

It's important to manage complexity. The more complex a system becomes, the harder it is to ensure required behaviour without unwanted effects. However, the more complex the problem, the more complex the software, and there's no avoiding this necessary complexity . But, if complexity is carefully compartmentalized (broken into smaller pieces with like behaviour requirements), human beings can still manage it.

Many approaches have been devised to reduce complexity like 'divide-and-conquer' where the system is broken down into small, manageable parts that together provide the complete system behaviour. It's proven that decoupling parts from each other (minimizing interconnectedness) can dramatically improve correctness and maintainability. Modularization and packaging support this.

Component-based software development separates implementation from interface, allowing software components to be swapped-out similar to hardware components E.g., a client component can be written to access a standard telephony interface without knowing the implementation of the interface; and this client can be used with different implementation components, depending on the underlying telephony network (cellular, PSTN, VoIP, etc.) the product supports.

Legato is designed to make it easier to build systems using a component-based model.

Decoupling components and hiding implementation details within components (behind their interfaces) has a major impact on maintainability:

Build Apps - Learn


o Clearly defining interface and components' roles and responsibilities allow defect sources to be isolated more easily.

o Components can be swapped out with stubs, and interfaces can be instrumented to gather more troubleshooting information.

o Component changes that don't affect its interfaces are constrained to that component. This

supports refactoring .

o Test suites can be applied to components implementing the same interface so test reuse is also supported.

Component-based software development also enables creative interconnection of components in previously unimagined ways to discover unique new solutions.

Components designed for reuse with simple, clean interfaces using standard data types and methods can be recombined into different arrangements that exhibit different overall system behaviours. Web mashups can combine previously-constructed web services into completely new applications because those web services provide well-defined interfaces using standard access mechanisms and data formats. The mashup doesn't care about how the web services are implemented; the mashup only cares about what the interfaces provide.

A further potential of component-based development is the ease of sharing (for free or for pay) of these reusable components. If a component is very useful to others, it can be shared and reused in accordance with the license that the author has chosen to release it under.

Legato Components

In the Legato world, each component is kept in its own directory. The name of the directory is also the name of the component.

The component can contain any number of source code files, pre-compiled binary files, resource files (e.g., audio files or images), or whatever files the component needs.

Each component must have a Component.cdef file. This file describes the component to the

Legato Build. It lists what source files the component includes, what interfaces it uses or implements, what resource files it includes, and what files it needs in the target host runtime environment.

Components that have source code files can be included in executables inside apps. The build tools will generate the appropriate start-up code for the executable to ensure that the component gets initialized when the executable is started.

Component Programming Model

Generally, Legato components are written using an event-driven model. Callback functions called "event handlers" (or "handlers" for short) are attached to specific events, and when events occur, the thread's event loop calls the appropriate handlers.

Every component implements a special initialization function (COMPONENT_INIT in C). That function

does whatever initialization is required for that component (e.g., initializes data structures, registers event handlers, starts threads, etc.) and returns. The process's main thread (auto-generated by the Build) runs all the component initializers for all components in the executable and then enters the Legato event loop. The event loop then reacts to events by and calling registered handlers.

This model allows multiple components to be deployed to the same process and even share a single thread within that process, without having to know anything about each other. This reduces the risk of multi-threaded race conditions and saves stack memory space, while simplifying many programming tasks.

Build Apps - Learn


Sometimes the judicious use of threads can considerably simplify a program, so multithreading is also supported by Legato, along with the usual thread synchronization tools (mutexes, semaphores, etc.) and the addition of queued function calls.

If a component blocks a shared thread, it blocks every component sharing that thread. So, to maximize a component's reusability in different programs, it's best to avoid blocking the main thread. Legato components can start their own, private threads to avoid this. And any thread can run its own event loop if an event-driven thread with blocking event handlers is desired.

Legacy Code

Sometimes you'll have a legacy program you want to include in your app without rewriting it in the style of a Legato component. This can be done by building your legacy app using your normal build system (but using the appropriate cross-toolchain provided for your target device) and bundling the built programs and libraries into the app.

Interfaces

To maximize component reuse, it's vital components be designed for reuse. Reusability partly depends on portability, which the Legato framework provides, but it also depends largely on interoperability. Reusable components must be designed for interoperability with as many other things as possible, including things that don't exist - yet!

Interface design is the most important factor to make something interoperable. Standardized data types and interaction methods must be used, and the simpler the interfaces, the better.

Legato embraces the philosophy that developers should always be allowed to choose the implementation language best suited to the task at hand, regardless of the components used. Some developers are better at programming in certain languages, and some languages are better suited to solving certain problems. That's why Legato provides developers with an easy way to interface components with each other, even if they have been written in different languages.

A common example of a programming-language-independent interface is a networking protocol. But networking protocols come with pitfalls and overhead, things like endian issues, race conditions, protocol stack framing overheads and poor processing time. Networking protocols also tend to require a lot of hand coding specific to the protocol implementation.

Legato supports networking, if that's what's needed, but it also has tools to implement much lighter-weight, language-independent communication between components that exist on the same host device or even running within the same process.


Function Call APIs

Virtually all programmers are familiar with function calls. While Legato allows normal libraries to use their specific programming-language function call interfaces, Legato also supports language-independent function call interfaces.

Using a simple interface definition language (IDL), you can create a function call API implemented in one language and called from another.

The implementation code (the server) can run in a different process, or even in a different application (in a different sandbox), than the client code that uses that implementation. The Legato build system automatically generates the code needed to marshall parameters and return codes into messages, and send them over the IPC system.

See API Files for more information.

Build Apps - Learn


Configuration

This topic describes how target device configuration works in Legato.

Also see Manage Config Tree

Device configuration data is vital for most applications. Seldom are all devices in an application identical. Usually, there's some kind of customization on each device: it may be a complex set of user preferences, or it may be just a simple node name. Regardless of the device's customization, the device needs to be:

o stored somewhere it can be retrieved quickly

o easy to modify programmatically from within the device application code

o easy to view and modify remotely via generic network or managed portal service

o protected from

malicious snooping and vandalizm

multi-threaded race conditions

untimely device reset or power loss

o

Structure

Configuration data is stored in a tree structure, where each non-leaf node can contain any number of child nodes, each with its own name. At the leaves of the tree, the nodes can contain data.

This tree structure allows configuration data items to be uniquely identified using path names, much like file system paths, which makes it much easier to access configuration data via HTTP, SNMP, OMA-DM, and other protocols. It also allows the configuration database to be explored using tree walking algorithms and tools.

Transactions

Configuration data can be shared by multiple processes and threads. This can sometimes result in race conditions that can threaten data integrity. For example, if threads A and B both use data fields X and Y, it could be bad if thread A interrupts thread B to read those fields just after thread B has updated field X and is about to update field Y to be consistent with the new value of field X.

A possible reset or power loss may occur at any time, and we must be sure that would not corrupt the configuration data. For example, if power fails just after field X has been updated, but before field Y gets updated to match the new value of field X, then the configuration data could be in an invalid state. Transactions are used to prevent these sorts of problems.

Before a change can be made to configuration data, a write transaction must be started. All changes are made in the context of such a transaction, and when the changes are complete, the transaction can be "committed". If a fault prevents the entire set of changes from being applied on commit, or if the transaction is cancelled before it is committed, then none of that transaction's changes will be applied.

Transactions can also be started for reading only. A write transaction will be allowed to start while there is a read transaction in progress. But the commit process will block write transactions until the read transactions have finished. This ensures that anyone reading configuration data fields will see only field values that are consistent.

Build Apps - Learn


To prevent denial of service problems (either accidental or malicious), transactions have a limited lifetime. If a transaction remains open for too long, it will be automatically terminated; the configration database will drop its connection to the offending client.

Backward/Forward Compatibility

For example, to support a new recurring wake-up schedule that supports waking on particular days of the week, the wake schedule configuration data may need to be completely re-structured. There are several ways to do this.

One approach is to have a "configuration data upgrade" utility run when the new software is installed. However, if the new software upgrades the configuration data and then fails to fully boot, and the device is forced to fall-back to the old software, then the old software won't be able to read its configuration data anymore. This can be mitigated by keeping a complete backup copy of the configuration data prior to the software upgrade, but this either consumes space in the device's non-volatile memory or it consumes time and over-the-air bandwidth to make backup copies elsewhere in the network.

However, the recommended approach is to:

o have newer software understand the configuration data structure used by previous versions of the software;

o never write to the configuration data unless settings are being changed;

o when changing settings, write the configuration data using the newest format;

o leave the older version of the configuration data along-side the newer version (in case of later software "downgrade");

o if both multiple versions of the same configuration data are found, use only the newest that is understood by the current running software.

Configuration Change Notifications

Sometimes, action needs to be taken whenever a configuration data field changes value. The Configuration Data API allows client software to register for notification when changes are committed to a particular branch of the configuration tree.

Access Control

Because the behaviour of applications can be affected by the configuration data that they use, configuration data can be used as an attack vector for malicious software. As a result, access to configuration data must be strictly controlled when there is any possibility that malicious software may be allowed to run on a device.

The Configuration Data system separates each applications' configration data only allowing access to its own data.

Event-driven Programming

In event-drivent programming, the flow of a program is determined by events triggered through a defined interaction (e.g., user interaction, exceeding threshold limit, etc. ). Usually, a main loop listens for events, and then triggers a callback function when an event is detected.

Overall, Legato components are written using an event-driven model. Callback functions are attached to specific events, and when events occur, the thread's event loop triggers the appropriate callbacks. Legato components can also start other threads that run their own Legato event loops.

Build Apps - Learn


Every component implements an initialization function called at process start-up by the main thread. That function does whatever initialization is required for that component (e.g., initializes data structures, registers callbacks, starts threads, etc.) and returns. After all initialization functions have run to completion and returned, the main thread enters the Legato event loop and begins reacting to events and calling registered callbacks.

This allows multiple components to be deployed to the same process and even share a single thread within that process, without having to know anything about each other. This reduces the risk of multi-threaded race conditions and saves stack memory space.

Beware one drawback is that if a component blocks a shared thread, it blocks every component sharing that thread.

Sometimes, the judicious use of threads can considerably simplify a program, so multi-threading is also supported by Legato along with the usual thread synchronization constructs (mutexes, semaphores, etc.).

Event Loop API

Legato's Event Loop API uses a central event loop that calls event handler functions in response to event reports . See Event Loop API

Software components register their event handler functions with the event system (either directly through the Event Loop API or indirectly through other APIs that use the Event Loop API) so the central event loop knows the functions to call in response to defined events.

Every event loop has an event queue , which is a queue of events waiting to be handled by that event loop.

The following different usage patterns are supported by the Event Loop API:

Deferred Function Calls

Publish-Subscribe Events

Layered Publish-Subscribe Handlers

Dispatching Function Execution to Other Threads

Power Management

Peripheral device power management is usually handled by device drivers and the operating system. If a device isn't in use, the driver automatically keeps that device in its lowest power state.

App behaviour drives power consumption. If app code is uses a peripheral device when it doesn't need to, power will be wasted. Power is also wasted if app code runs busy-wait loops or periodically polls for events.

To conserve power, apps should register call-back functions only triggered when events occur. This way app code only runs when an event occurs, rather than waking up to check for events that haven't happened. Every CPU cycle uses power, so when a power-sensitive app is woken up, it should execute as few instructions as possible before going back to sleep.

When all threads are sleeping, the O/S will reduce the CPU power state automatically. When an event handler function returns back to the Legato event loop, it puts the thread to sleep (unless there's another event waiting). If your thread isn't running the Legato event loop, block your thread to

put it to sleep when it's not working through poll() , select() , read() , write() , recv() ,

etc.

Build Apps - Learn


If you use a periodic timer (like Timer API) to wake up your app, it will consume power. Set the timer period as long possible to conserve power, and let the O/S go into deeper sleep states.

To maximize power savings, the system can use the Linux auto-sleep feature. Unless the system is

busy processing a non-deferrable event, this feature puts the hardware into a SUSPEND state where

all peripherals and the CPU are placed into low-power mode. Apps with the appropriate credentials have the option to control the system power state while performing critical operations.

Use Legato's Power Manager to control the system's wake-up (powered) state. Operations needing fast response times or those resulting in high interrupt rates may benefit from keeping the system awake. This provides better performance, but worse power efficiency.

See Manage Device Power for info on how to write power-efficient apps.


Inter-process communication (IPC) allows communication between different processes. A process is one or more threads running inside its own, isolated address space.

Threads running inside the same process communicate easily with each other; they read and write the same data inside their shared address space.

Threads running inside two different processes can't access each other's data; they need IPC to communicate.

Legato's Low-Level Messaging API and API Files provide IPC services without all the coding, packing/unpacking, and security headaches that come with using other methods directly (e.g., network sockets or named pipes).

Legato has built-in IPC features. The language-independent, function-call-oriented IPC approach is automatically handled with the ifgen tool and the Build.

By default, each app runs in its own sandbox. When an app is constructed, all the IPC services it needs are declared. At runtime, the Supervisor and the Service Directory enforce that only those approved IPC services are accessed by the app. Approval is specified through "bindings".

Client-side interfaces are "bound" to server-side interfaces through system configuration files. This allows reconfiguration of systems into new systems just by rerouting bindings, without having to modify the client or server software. Bindings make code more reusable. For example, if an app controls an LED, but the LED is connected to a different GPIO pin on different target devices, that same app can be used on both devices, with its LED control interface bound to different GPIO pin control services in each device.

Using language-independent IPC makes components inherently more reusable, creates opportunities for function isolation in different processes or different app sandboxes, and automatically creates potential debugging trace points.

Another approach Legato provides for IPC is low-level messaging APIs: C Runtime Library. This let's you custom build IPC to suit your needs, but may make it harder to interact with code written in other languages.

Related info

Interfaces

API Files

Use IPC

Build Apps - Learn


Definition Files

Services APIs

Internationalization

Legato provides string manipulation functions that support UTF-8 encoding.

Other internationalization and localization features are left up to app developers.

Logging

Logging is a critical part of any embedded development framework. Most devices can't display error or warning messages and don't have a human user monitoring them. Even when a device does have a display and a user watching it, the log messages often don't help the device's primary user. Displaying messages on a screen doesn't support remote troubleshooting; especially when the device is hidden from view inside a piece of equipment or located in remote geographic regions.

Use Logs

Command line log tool

Logging API

LWM2M Data

Legato supports the LWM2M standard, which specifies a set of common interfaces and data models to enable interoperability between devices and remote services.

LWM2M provides necessary device management functions like secure device on-boarding and Over-The-Air (OTA) upgrade and configuration.

Legato provides pre-built APIs that use LWM2M standards to access the AirVantage cloud service.

Manage AirVantage Data

AirVantage Data API

AirVantage Connector API

Component defintion Assets

Updates

The Legato application framework is designed to solve many difficult problems surrounding updating software on devices that are operating in the field:

o Atomic update of libraries, executables, resource files, and configuration settings.

o Autonomous recovery from failed update attempts (e.g., due to power loss or connection loss).

o Autonomous roll-back when newly updated software fails.

Build Apps - Learn


o Reduce flash consumption by sharing read-only app files that are the same in different software versions.

Software updates are primarily carried out by the Update Daemon but, the Supervisor and start-up code also have a role to play in rolling-back when updates fail.

See

Update Process

Update Pack Format

Software Update

update target tool

Build Apps - Build Apps


Build Apps

Create Apps

Use IPC

Client/Server

Add Things

Deploy Multiple Components

Overview

An application (app) is a collection of one or more processes running one or more executables. Each executable can make use of libraries and other resource files bundled into the app.

Legato apps automatically run inside a secure sandbox, and don't require any configuration. You just build an app, install it, and it automatically runs in a sandbox.

Legato apps can automatically start at boot, and are monitored by the Supervisor daemon. If an app fails in the field, the Supervisor can perform autonomous fault-recovery actions like restarting a process or rebooting.

Just like any embedded Linux platform, you can install individual executables, libraries, resource files, etc., you can write init scripts, and you can implement security sandboxes, fault monitoring, and fault recovery. But Legato provides the platform to do all that so you can focus on your business' unique value-add instead.

Create Apps

These are the basic steps to build an app written in C that logs Hello World. when the process it's

in starts up:

o Create Component

o Create App

o Build App

o Install App to Target

o Use App

Then you're ready for the next level: Add Things, Use IPC, and Deploy Multiple Components.

Sample Directories and Files

Typical apps have directories and files that look this:

helloWorld/

helloComp

Component.cdef

hello.c

helloWorld.adef



Create Component

Complete these steps to create a component: Create Directory, Create C Source File, and Create cdef File

Use IPC

Let's explore how to use inter-process communication (IPC) between components:

o Define a simple interface protocol that clients can use to ask servers to "Greet".

o Create a server that prints "Hello world" whenever a client asks it to "Greet",

o Create a client that asks the server to "Greet",

Here's what it looks like at runtime:

When we show the static view of components inside executables, it looks like this:

Note that each interface has

o an interface protocol

o a friendly name.

In our example, the client and server both use the same friendly name "hello" for their interfaces, and must use the same protocol (or they wouldn't be able to communicate with each other!).



Define Interface Protocol

First, create a directory for our little project and change directories:

$ mkdir helloIPC

$ cd helloIPC

Next, define the interface protocol to use between the client and the server.

To create our greet function-call API, we create a definition file called "greet.api".

$ gedit greet.api

Add this inside greet.api:

FUNCTION Greet

(

);

This will declare a function called Greet that takes no arguments and returns nothing.

Create Server Component

Next, create a server component called greetServer that offers a greeting service called "hello" to

be accessed using our simple "greet" API. Do this by creating a file called "Component.cdef" in a new directory called "greetServer".

$ mkdir greetServer

$ gedit greetServer/Component.cdef

NOTE

Keeping components in separate directories from each other is a requirement of the framework.

greetServer/Component.cdef should contain the following:

provides:

{

api:

{

hello = greet.api

}

}

sources:

{

greetServer.c

}



This declares that the component named greetServer (the name of the directory is the name of

the component) provides a service called hello accessed using the API defined in greet.api

where the source code can be found in the file greetServer.c .

NOTE

The source code file name extension is used to identify the programming language it's written in.

To implement the server (in C), create a file greetServer/greetServer.c :

$ gedit greetServer/greetServer.c

Make it contain the following:

#include "legato.h"

#include "interfaces.h"

void hello_Greet(void)

{

LE_INFO("Hello world.");

}

COMPONENT_INIT

{

}

The file interfaces.h is auto-generated based on the contents of greet.api and greetServer's

Component.cdef . It'll contain a prototype of the function hello_Greet() , which we implemented

in greetServer.c .

The function hello_Greet() will be called when a client binds to our hello service and calls the

function Greet() . The name hello_Greet follows this pattern:

'_'

The is the name given to the provided interface. In our example, it's the name

hello before the = in the line hello = greet.api .

NOTE

If you forget to implement a service function on the server or if you give it the wrong name, the link stage will fail and complain that the symbol is unresolved. You'll know you missed a function, and you'll be able to see what the correct name of the function should be.

Create Client Component

Now that we have a server, let's create a client to use its service.

First, create a directory for the greetClient component and a file in it called Component.cdef:



$ mkdir greetClient

$ gedit greetClient/Component.cdef

greetClient/Component.cdef should contain:

requires:

{

api:

{

hello = greet.api

}

}

sources:

{

greetClient.c

}

To implement the client using C, create a file called greetClient/greetClient.c :

$ gedit greetClient/greetClient.c

Make it contain the following:

#include "legato.h"

#include "interfaces.h"

COMPONENT_INIT

{

hello_Greet();

}

The interfaces.h file the client includes is different than the one the server uses. This client one

is specially generated based on the contents of greetClient/Component.cdef and greet.api

.

In the client, we use the component initializer to call hello_Greet() at start-up.

You can add a message to the COMPONENT_INIT so the logs will show the client calling the server:

{

LE_INFO("greetClient is calling hello_Greet \n");

hello_Greet();

}

Declare IPC Bindings

You can create an Application Definition .adef file with an Extern section to declare it's available for binding:

extern:



{

helloWorld.greetServer.greet.api

}

You only need to do this if you want to leave your interface unbound, and bind it later in the System Definition .sdef file bindings section.

Client/Server

After you've created your client and server programs with their interfaces bound to each other, this is how you create the app.

Create an app definition file called helloWorld.adef like this:

$ gedit helloWorld.adef

executables:

{

myServer = ( greetServer )

myClient = ( greetClient )

}

processes:

{

run:

{

(myServer)

(myClient)

}

}

bindings:

{

myClient.greetClient.hello -> myServer.greetServer.hello

}

This defines two executable programs called myServer (containing the greetServer component) and

myClient (containing the greetClient component).

It then starts one instance of myServer and one instance of myClient , and binds

myClient.greetClient.hello to myServer.greetServer.hello .

Then run mkapp to build everything and package it up into an app.

$ mkapp helloWorld.adef -t wp85

You'll now have a file called "helloWorld.wp85" that contains your app.

You can install and run it using instapp, see Install App to Target for details.



Add Things

After you've created your executable and turned it into an app (.adef), you can add others things you might need (e.g., a third-party library, some data files, a script or a legacy program built on another system).

To add other files to applications, you add other sections to your application's .adef file.

Here's a sample of how to add an audio file and a third-party library:

bundles:

{

file:

{

[r] audio/alert.wav /usr/share/sounds/

[r] third-party/foo/lib/foo.so.1 /lib

}

}

The file: subsection of the bundles: section will copy the file ./audio/alert.wav from the build

Legato Reference Manual - Linkwave - M2M...

Documents

Transcript of Legato Reference Manual - Linkwave - M2M...