nanoFramework.Runtime.InFieldUpdate.Provider 1.0.19

Welcome to the .NET nanoFramework nanoFramework.Runtime.InFieldUpdate Library repository

This repository contains the nanoFramework.Runtime.InFieldUpdate class library.

Build status

Component	Build Status	NuGet Package
nanoFramework.Runtime.InFieldUpdate
nanoFramework.Runtime.InFieldUpdate.Provider

What is In-Field Update

In-Field Update (IFU) lets a deployed device replace its own application (deployment) and nanoCLR firmware without a debugger or host tool attached.

In the industry this is also commonly called OTA (over-the-air) update. The name is a little misleading: an update can reach a device over Wi-Fi or cellular, but just as well over Ethernet, a serial link, a USB stick or an SD card. What matters is that the device updates itself in the field, which is why this library uses the term In-Field Update.

IFU is built on MCUboot: each image has a primary slot that runs and a secondary slot where a new image is staged. On the next reboot MCUboot swaps the new image in as a test image; if the new application does not confirm itself, the previous image is restored on the following reboot.

This library is the managed API to that mechanism: query the images on the device, stage a new one through an update session (with resume after interruptions), confirm or revert, and reboot. Every session operation returns an UpdateSessionResult saying exactly what happened.

// stage a new deployment image, chunk by chunk, as it arrives from the provider
if (UpdateManager.StartUpdateSession(ImageType.Deployment, totalLength, out UpdateSession session)
    != UpdateSessionResult.Success)
{
    return;
}

while (!session.IsComplete)
{
    if (session.Write(NextChunkFromServer()) != UpdateSessionResult.Success)
    {
        return;
    }
}

if (UpdateManager.CompleteUpdateSession(session) == UpdateSessionResult.Success)
{
    UpdateManager.RequestReboot();
}

// ...and in the new application, once it has checked it works:
UpdateManager.ConfirmDeploymentImage();

Documentation

• Overview - images, slots, update lifecycle and states, API map.
• Querying images - GetStatus, GetPrimaryImageInfo, GetSecondaryImageInfo, GetImageList, ImageInfo and printing them.
• Update sessions - staging an image, resuming an interrupted download, session rules and result codes.
• Confirm and revert - ConfirmDeploymentImage, RequestDeploymentRevert, RequestClrRevert, RequestReboot and the test cycle.
• Writing an update provider - how to build an update library that fetches images from a server or other provider, end to end, on the IUpdateProvider contract from the nanoFramework.Runtime.InFieldUpdate.Provider package.

Packages

• nanoFramework.Runtime.InFieldUpdate - the core API above. All an application needs to stage, confirm and revert images.
• nanoFramework.Runtime.InFieldUpdate.Provider - the contract for update libraries: IUpdateProvider (where images come from) and UpdateAgentOptions (chunk size, retry cap, confirm hook). Pure managed code on top of the core package.

Samples

• IFU_Management - lists the images and slots on the device.
• IFU_SessionUpdate - start, pause, resume and complete an update session with an image built in RAM.
• IFU-blink-app - a minimal application that confirms itself on boot, to build as an update image.

Feedback and documentation

For documentation, providing feedback, issues and finding out how to contribute please refer to the Home repo.

Join our Discord community here.

Credits

The list of contributors to this project can be found at CONTRIBUTORS.

License

The nanoFramework Class Libraries are licensed under the MIT license.

Code of Conduct

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behaviour in our community. For more information see the .NET Foundation Code of Conduct.

.NET Foundation

This project is supported by the .NET Foundation.