<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html data-context="Build Apps" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type"/>
<title>Update Control API  - Legato Docs</title>
<meta content="legato™ is an open source Linux-based embedded platform designed to simplify connected IoT application development" name="description"/>
<meta content="legato, iot" name="keywords"/>
<meta content="18.01.0" name="legato-version"/>
<meta content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" name="viewport"/>
<link href="resources/images/legato.ico" rel="shortcut icon"/>
<link href="resources/images/legato.ico" rel="icon" type="image/x-icon"/>
<link href="resources/images/legato.ico" rel="shortcut icon" type="image/x-icon"/>
<link href="resources/images/legato.ico" rel="apple-touch-icon" type="image/x-icon"/>
<link href="resources/css/style.css" media="screen" rel="stylesheet" type="text/css"/>
<link href="resources/css/font-awesome.css" rel="stylesheet" type="text/css"/>
<!--[if IE]>
        <script src="resources/js/html5shiv.js"></script>
        <script src="resources/js/respond.js"></script>
        <![endif]-->
<script src="https://code.jquery.com/jquery-2.2.3.min.js"></script>
<script src="resources/js/main.js"></script>
<script src="tocs/Build_Apps_API_Guides.json"></script>
</head>
<body>
<noscript>
<input class="modal-closing-trick" id="modal-closing-trick" type="checkbox"/>
<div id="nojs">
<label for="modal-closing-trick">
<span>You seem to not have Javascript <a href="http://enable-javascript.com">enabled</a>, so site functionality like the search and navigation tree won't work.</span>
</label>
</div>
</noscript>
<div class="wrapper">
<div class="fa fa-bars documentation" id="menu-trigger"></div>
<div id="top">
<header>
<nav>
<a class="navlink" href="/">Introduction</a><a class="navlink selected" href="buildAppsMain.html">Build Apps</a><a class="navlink" href="buildPlatformMain.html">Build Platform</a><a class="navlink" href="aboutMain.html">About</a>
</nav>
</header>
</div>
<div class="white" id="menudocumentation">
<header>
<a href="/"> <img alt="Back to Legato Homepage" id="logo" src="resources/images/legato_logo.png"/></a>
<h2>/ Build Apps</h2>
<nav class="secondary">
<a href="buildAppsConcepts.html">Concepts</a><a class="link-selected" href="apiGuidesMain.html">API Guides</a><a href="tools.html">Tools</a><a href="howToMain.html">How To</a><a href="sampleApps.html">Sample Apps</a>
</nav>
<nav class="ui-front">
<i class="fa fa-search" id="search-icon"></i>
<input id="searchbox" placeholder="Search"/>
</nav>
</header>
</div>
<div id="resizable">
<div id="left">
<div id="tree1"></div>
</div>
</div>
<div class="content">
<div class="header">
<div class="headertitle">
<h1 class="title">Update Control API </h1> </div>
</div><div class="contents">
<div class="textblock"><p><a class="el" href="le__update_ctrl__interface_8h.html">API Reference</a></p>
<hr/>
<p>This API is used by privileged apps to control the software update process. It can be used to:</p><ul>
<li>prevent updates from happening or</li>
<li>control the marking of a system update as "good" or "bad".</li>
</ul>
<p>Note that this is not part of the Update API (le_update) because the Update API can be used by less trusted apps to feed signed/encrypted updates to the Update Daemon, and we may not trust those same apps to have the ability to prevent someone else from updating or rolling-back the system.</p>
<h1><a class="anchor" id="le_updateCtrl_prevention"></a>
Preventing Updates During Critical Operations</h1>
<p>To protect against updates during critical periods of operation (such as when performing an emergency call in response to a vehicle collision), the following functions are provided:</p>
<ul>
<li><a class="el" href="le__update_ctrl__interface_8h.html#acdbc9dcc05455f0dd1020b875909c3ed">le_updateCtrl_Defer()</a> - prevent all updates until further notice.</li>
<li><a class="el" href="le__update_ctrl__interface_8h.html#ab3955f0e34df43a5fbe3e9eae16040d4">le_updateCtrl_Allow()</a> - allow updates to go ahead.</li>
</ul>
<p>Updates will not be allowed to go ahead until no clients are deferring updates. So, if client A and client B both call <a class="el" href="le__update_ctrl__interface_8h.html#acdbc9dcc05455f0dd1020b875909c3ed">le_updateCtrl_Defer()</a>, updates will be deferred until both client A and client B have called <a class="el" href="le__update_ctrl__interface_8h.html#ab3955f0e34df43a5fbe3e9eae16040d4">le_updateCtrl_Allow()</a>.</p>
<p><a class="el" href="le__update_ctrl__interface_8h.html#acdbc9dcc05455f0dd1020b875909c3ed">le_updateCtrl_Defer()</a> will also prevent rollbacks unless a fault triggers the Supervisor to restart the framework or reboot the target. See below for more information on rollbacks.</p>
<h1><a class="anchor" id="le_updateCtrl_probation"></a>
Controlling the Probation Period</h1>
<p>Whenever a new system is started, a probation period begins. If the system stays running for the entire probation period, the system is marked "good". But, during the probation period, if an app faults enough times in a short enough period for the Supervisor to give up on trying to start it, the system update is marked "bad" and the system is rolled-back to the last known "good" system.</p>
<p>In some cases, a customer may want to extend the probation period of their new system for a non-deterministic amount of time, until it has had a chance to perform some action in the real world (such as successfully "phoning home" at least once).</p>
<p>To support this, the functions <a class="el" href="le__update_ctrl__interface_8h.html#a88e55c6e0ee5c2cf52e6fcb75a9db87e">le_updateCtrl_LockProbation()</a> and <a class="el" href="le__update_ctrl__interface_8h.html#a4ba5ace59bfe352c518c3f1eae6d0448">le_updateCtrl_UnlockProbation()</a> are provided, where each call to "Lock" must be matched with a call to "Unlock".</p>
<p>For those who want to mark "good" at some point of their own determination, regardless of how long the system has been up, <a class="el" href="le__update_ctrl__interface_8h.html#a8eaa5f533d5d677397642c7b44ce7bb3">le_updateCtrl_MarkGood()</a> is provided.</p>
<p>And for those who want to mark the system "bad" and trigger a rollback at some point of their own choosing, <a class="el" href="le__update_ctrl__interface_8h.html#a9f6a3bf7a830eb04823ea6188c12109c">le_updateCtrl_FailProbation()</a> is provided.</p>
<p>Calls to any of the functions that affect the probation period are ignored if the probation period is already over (if the system is already marked "good"). Once it is "good", it stays "good".</p>
<p>If someone tries to update the system while it is still in its probation period, the update will be refused. To override this, call <a class="el" href="le__update_ctrl__interface_8h.html#a9f6a3bf7a830eb04823ea6188c12109c">le_updateCtrl_FailProbation()</a> or <a class="el" href="le__update_ctrl__interface_8h.html#a8eaa5f533d5d677397642c7b44ce7bb3">le_updateCtrl_MarkGood()</a> to end the probation period before trying to apply the new system update.</p>
<dl class="section note"><dt>Note</dt><dd>If a reboot occurs during the probation period, the probation period will start over. But, if the system reboots more than a few times without reaching the end of its probation period first, then the system will be rolled-back to the last known "good" system.</dd></dl>
<hr/>
<p class="copyright">Copyright (C) Sierra Wireless Inc. </p>
</div></div>
<br clear="left"/>
</div>
</div>
<link href="resources/css/jqtree.css" rel="stylesheet" type="text/css"/>
<script src="resources/js/tree.jquery.js" type="text/javascript"></script>
<script src="resources/js/jquery.cookie.js"></script>
<script src="https://code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script>
<link href="resources/css/perfect-scrollbar.min.css" rel="stylesheet"/>
<script src="resources/js/perfect-scrollbar.jquery.min.js"></script>
</body>
</html>
