Module firmware 

Firmware management, TS006-1.0.0.

This is the package a server uses to ask what a device is running, what upgrade image it is holding, and when to reboot into it. Getting the image onto the device is another matter, out of this specification’s scope; what this covers is everything around it: reporting the firmware and hardware versions, reporting whether the stored image is whole, authentic and meant for this hardware, deleting one, and scheduling the reboot at which an image is installed.

A device stores one programmed reboot at a time. It can be set as a moment in time (FirmwareCommand::DevRebootTimeReq) or as a countdown (FirmwareCommand::DevRebootCountdownReq), and either one replaces whatever was programmed before. Both have a value that cancels the reboot and a value that means now, and a device that reboots immediately never answers, because it is gone.

FirmwareManager holds that state for a device: the versions it reports, the image it is holding, and the reboot it has been given.

Examples

A server asks what the device would boot into, and schedules it:

use pamoja_lorawan::packages::firmware::{
    FirmwareCommand, FirmwareCommands, FirmwareManager, Image, UpImageStatus,
};
use pamoja_lorawan::Direction;

// A device running version 1.2.3 holds a valid image of 1.2.4, waiting to be booted.
let mut manager = FirmwareManager::new(0x0001_0203, 0xAABB_CCDD)
    .with_image(Image::valid(0x0001_0204));

// The server asks what it would boot into, and schedules a reboot in an hour.
let mut asked = [0u8; 8];
let mut len = FirmwareCommand::DevUpgradeImageReq.encode(&mut asked)?;
len += FirmwareCommand::DevRebootCountdownReq { countdown: 3_600 }.encode(&mut asked[len..])?;

let mut out = [0u8; 16];
let answered = manager.heard(&asked[..len], &mut out)?;
let answers: Vec<FirmwareCommand> = FirmwareCommands::new(Direction::Uplink, &out[..answered])
    .map(|answer| answer.unwrap())
    .collect();
assert_eq!(
    answers[0],
    FirmwareCommand::DevUpgradeImageAns {
        status: UpImageStatus::Valid,
        next_version: Some(0x0001_0204),
    }
);
assert_eq!(manager.reboot_in_s(), Some(3_600));

Structs

DeleteStatus

Why a device would not delete the image it was asked to, table 13.

FirmwareCommands

Walks the commands packed into one firmware management message.

FirmwareManager

The firmware management package running on a device, TS006-1.0.0.

Image

The firmware upgrade image a device is holding.

Enums

FirmwareCommand

One command of the firmware management package.

UpImageStatus

What a device says about the firmware upgrade image it is holding, table 10.

Constants

COUNTDOWN_CANCEL

The countdown that cancels a programmed reboot, section 3.4.

COUNTDOWN_NOW

The countdown that means as soon as possible, section 3.4.

MAX_COMMAND

The longest firmware management command, in bytes.

PACKAGE

The identifier of this package, section 3.

PORT

The port the firmware management package is spoken on, section 3.

REBOOT_CANCEL

The reboot time that cancels a programmed reboot, section 3.3.

REBOOT_NOW

The reboot time that means as soon as possible, section 3.3.

VERSION

The version of this package implemented here, section 3.