Secondary Action handler "get-firmware-info" result when secondary is not yet installed

Technical Support
, , ,
1

I’m working on implementing some action handlers for secondaries and I wanted to clarify what the “correct” behaviour of get-firmware-info is for a situation where the secondary is not yet installed. The documentation at First Steps With Subsystem Updates | Toradex Developer Center isn’t clear to me.

Should the handler:

  • return “failed” with an appropriate error string?
  • return “ok” but with a zeroed out file size and hash?
  • Exit with code 64 and pass through to Aktualizr’s default handling?

Implementing the former led me to observe that the secondary in question wasn’t listed in the web platform for the device until a version was actually installed, (which would seem to imply you could not push an OTA to that device until at least one version was already installed).

Zeroing the returned size and hash doesn’t exactly seem like the intended implementation, and the documentation recommends against relying on the default handler in order to better handle situations where a secondary might have its own storage (say, a microcontroller) and be pre-loaded with some firmware)

Thanks!

2

Hi, I’m the Toradex AI Assistant.

I might make mistakes or occasionally get you wrong. Our support team will step in if needed.

For the get-firmware-info action when the secondary is not yet installed, the correct behavior depends on your specific use case, but the documentation provides clear guidance on the expected output structure(1).

Recommended Approach: Return “ok” Status with Null/Empty Values

According to the documentation, when implementing the get-firmware-info action, your handler should return a JSON string with this structure(1):

  • name (string): The name of the currently installed target (package); if this field is not present (recommended) or it is set to null, it will be automatically determined from a “target name” file(1)
  • sha256 (string): The SHA-256 checksum of the currently installed version of the firmware file; if this field is not present or is set to null it will be automatically determined based on the current firmware file(1)
  • length (integer): Size in bytes of the currently installed firmware file. This field must be set only when sha256 is set and it will be ignored otherwise(1)
  • status (string): This can be set to one of the following values: ok or failed(1)
  • message (string): A message to be shown in the aktualizr-torizon logs (useful for debugging)(1)

Handling Non-Installed Secondaries

For a secondary that is not yet installed, you should:

  1. Return “ok” status with null values for sha256 and name(1)
  2. Do not set the length field since it’s only used when sha256 is set(1)
  3. Include a descriptive message for debugging purposes(1)

The documentation specifically notes that the automatic determination based on the firmware file “is not ideal though because the target subsystem may not be running this exact firmware binary (if, for example, that component was upgraded not via the Aktualizr update client or if the last firmware was not applied due to some previous error)”(1).

Important Considerations

The documentation mentions that “The file may not exist though if there was no previous successful installation”(1), which directly addresses your scenario. This suggests that the system is designed to handle cases where no firmware has been installed yet.

Your observation about the secondary not appearing in the web platform until a version is installed aligns with the expected behavior, as the system needs to establish the subsystem’s existence through the action handler’s response.

Best regards, Toradex AI Assistant.

Did you like my answer? :+1: :-1:

If I answered your question, please tick the “Solution” checkbox.

For follow-up questions to me, please use @ToradexAI in your post.