11.6. Firmware Management¶
11.6.1. Manifests & Packages¶
To ensure interoperability across systems, GEISA uses a defined firmware
package format. The package format is the same as the application package
format (see Application Management): a gzip compressed tar archive
containing the manifest, named manifest.json, and all of the artifacts
listed in the manifest. The format and contents of the firmware artifacts are
not defined by GEISA and are specific to the device they have been built for.
GEISA defines the package format and the manifest to allow an EMS to load and
transfer firmware for any device from any vendor and to ensure a consistent
and secure firmware transfer process. The gzip compressed tar file is the
image that the EMS transfers to the device using the LwM2M mechanisms discussed
below.
The firmware manifest format is provided in
geisa-firmware-manifest-schema.json. The format is substantially similar
to the application manifest (see Application Manifests); however, it only
includes artifacts, compatibility meta-data and signatures, omitting resource
allocations and permissions. Critically, the firmware manifest uses the LwM2M
Object 3 manufacturer and model-number fields to determine whether
the firmware package is compatible with the target device. The
firmware-version field allows the EMS to understand whether a package is an
upgrade or a downgrade.
Firmware manifests and the incorporated artifacts MUST be signed by the
publisher. Firmware manifests in deployment packages MAY be countersigned by
the system operator. Device manufacturers are free to include multiple
artifacts within a firmware package. This capability can be used to provide
images for specific subcomponents within a device. Manufacturers may use the
image-name, image-type or both to distinguish between different
artifacts. The EMS MUST preserve the manifest value within
geisa-firmware-manifest without any changes. Only the manifest’s
signatures block MAY be updated by the EMS. Typically, this is
done to allow system operator to counter-sign a package. The publisher
signature on the geisa-firmware-manifest MUST be retained, as it may be
required by the target device.
11.6.2. LwM2M Update Process¶
Firmware management is the process of updating the core operating system for an ADM conformant GEISA platform.
The LwM2M singleton object /5/0 Firmware Update represents the firmware
update process, not simply the firmware image stored on the device. Object
/5/0 is advertised during initial Registration, and object /5/0 is not
deleted by the GEISA platform client after an upgrade; only the /5/0/3
State and /5/0/5 Update Result resources are reset after an upgrade to
reflect the new baseline.
The multi-step Firmware Update transaction typically involves the EMS Observe
/5/0/3 State so that the GEISA platform client will provide asynchronous
updates of client state changes to the EMS, after which the EMS will proceed with
subsequent steps in the transaction. Although it is technically possible to
Observe resources /5/0/3 and /5/0/5 following initiation of the update
transaction, in order to avoid transaction dead locks or inconsistent state due
to race conditions, and to provide optional support for resource /5/0/14
Automatic Upgrade at Download, a GEISA ADM conformant EMS SHALL perform the
following:
Observe
/5/0/3 Statewhen object/5/0is advertised during GEISA platform RegistrationRead
/5/0/5 UpdateResult after Notification that/5/0/3 State = Idle
Depending on EMS capabilities, LwM2M allows either of the following methods for firmware image distribution to the GEISA platform:
PUSH (CoAP block-wise transfer) via the Write operation of the opaque binary image to resource
/5/0/0(Package)PULL via the Write operation to resource
/5/0/1(Package URI), allowing the GEISA platform to download via CoAP or HTTP as soon as practical.
The following sequence diagrams provide two examples of GEISA conformant
upgrades of the platform firmware. The first example demonstrates PUSH of the
firmware image to /5/0/0 Package, as shown in Figure 11.5
followed by the EMS performing a manual Execute /5/0/2 to trigger the
upgrade in Figure 11.6.
Figure 11.5 Firmware Over-the-Air Push Update¶
Figure 11.6 Firmware Over-the-Air Manual Activate¶
The second example, as shown in Figure 11.7, demonstrates the
PULL of the firmware image from the URL set by the EMS into /5/0/1 Package
URI. As shown in Figure 11.8, the ADM conformant GEISA
platform automatically executes the upgrade after the download per the EMS
setting /5/0/14 Automatic Upgrade = True.
Figure 11.7 Firmware Over-the-Air Pull Image Initiate¶
Figure 11.8 Firmware Over-the-Air Pull Automatic Download and Update¶