Skip to content

OcaFirmwareManager#

This document describes the controller implementation of OcaFirmwareManager. This class is documented in the AES70 standard as:

Optional manager that manages versions of the different firmware and software images of the device. May be instantiated at most once in any device., If instantiated, must have object number 3.

A device that does not support firmware updating may support the subset of this class's functions needed to report firmware version numbers to inquiring controllers.

This firmware manager offers a generic interface for updating OCA devices. The actual robustness of the update process is left up to the implementer. The interface allows for any of:

  • Fully transactional based uploads (i.e. only committing to the newly uploaded images after all component uploads have succeeded, and reverting back to the old images if any step fails)
  • Partly transactional based uploads (i.e. committing to a newly uploaded image after each individual component upload succeeds, possibly leading to a device containing a mix of old and new images)
  • Non-transactional based uploads guarded by golden images (i.e. accepting a 'weak' spot in the upload process where interruption may lead to a corrupt regular image, which is solved by loading a read-only failsafe ("golden") image in such cases that will allow recovery of the regular image)
  • Non-transactional based uploads that may lead to bricked devices

Overview#

Class Declaration#

namespace aes70::controller
{
  class OcaFirmwareManager : public OcaManager
  {
  public:
    OcaFirmwareManager(std::shared_ptr<connection> connection,
            uin32_t object_number);
    OcaFirmwareManager(const OcaFirmwareManager &o);

    // Control Methods
    // Calls GetComponentVersions and calls on_result or on_failure
    void GetComponentVersions(auto on_result, failure_callback on_failure);
    // Calls StartUpdateProcess and calls on_result or on_failure
    void StartUpdateProcess(auto on_result, failure_callback on_failure);
    // Calls BeginActiveImageUpdate and calls on_result or on_failure
    void BeginActiveImageUpdate(OcaComponent component, auto on_result, failure_callback on_failure);
    // Calls BeginActiveImageUpdate and does not wait for the response
    void BeginActiveImageUpdate(OcaComponent component);
    // Calls AddImageData and calls on_result or on_failure
    void AddImageData(OcaUint32 id, OcaBlob imageData, auto on_result, failure_callback on_failure);
    // Calls AddImageData and does not wait for the response
    void AddImageData(OcaUint32 id, OcaBlob imageData);
    // Calls VerifyImage and calls on_result or on_failure
    void VerifyImage(OcaBlob verifyData, auto on_result, failure_callback on_failure);
    // Calls VerifyImage and does not wait for the response
    void VerifyImage(OcaBlob verifyData);
    // Calls EndActiveImageUpdate and calls on_result or on_failure
    void EndActiveImageUpdate(auto on_result, failure_callback on_failure);
    // Calls BeginPassiveComponentUpdate and calls on_result or on_failure
    void BeginPassiveComponentUpdate(OcaComponent component, OcaNetworkAddress serverAddress, OcaString updateFileName, auto on_result, failure_callback on_failure);
    // Calls BeginPassiveComponentUpdate and does not wait for the response
    void BeginPassiveComponentUpdate(OcaComponent component, OcaNetworkAddress serverAddress, OcaString updateFileName);
    // Calls EndUpdateProcess and calls on_result or on_failure
    void EndUpdateProcess(auto on_result, failure_callback on_failure);

    // Observing Properties
    subscription observeComponentVersions(auto callback, failure_callback on_failure);

    // Property Changed Subscriptions
    subscription OnComponentVersionsChanged(auto callback, failure_callback on_failure);
  };
}

Methods#

GetComponentVersions#

void GetComponentVersions(auto on_result, failure_callback on_failure)

Calls the method GetComponentVersions in the remote device.

Parameters:#

  • auto on_result: A callable (e.g. a lambda) with the following arguments:
    • OcaList<OcaVersion> componentVersions
  • failure_callback on_failure: A callback which is called on error.

StartUpdateProcess#

void StartUpdateProcess(auto on_result, failure_callback on_failure)

Calls the method StartUpdateProcess in the remote device.

Parameters:#

  • auto on_result: A callable (e.g. a lambda) with 0 arguments.
  • failure_callback on_failure: A callback which is called on error.

BeginActiveImageUpdate#

void BeginActiveImageUpdate(OcaComponent component, auto on_result, failure_callback on_failure)

Calls the method BeginActiveImageUpdate in the remote device. If no result and error callback is specified, the method will be called without requesting a response.

Parameters:#

  • OcaComponent component
  • auto on_result: A callable (e.g. a lambda) with 0 arguments.
  • failure_callback on_failure: A callback which is called on error.

AddImageData#

void AddImageData(OcaUint32 id, OcaBlob imageData, auto on_result, failure_callback on_failure)

Calls the method AddImageData in the remote device. If no result and error callback is specified, the method will be called without requesting a response.

Parameters:#

  • OcaUint32 id
  • OcaBlob imageData
  • auto on_result: A callable (e.g. a lambda) with 0 arguments.
  • failure_callback on_failure: A callback which is called on error.

VerifyImage#

void VerifyImage(OcaBlob verifyData, auto on_result, failure_callback on_failure)

Calls the method VerifyImage in the remote device. If no result and error callback is specified, the method will be called without requesting a response.

Parameters:#

  • OcaBlob verifyData
  • auto on_result: A callable (e.g. a lambda) with 0 arguments.
  • failure_callback on_failure: A callback which is called on error.

EndActiveImageUpdate#

void EndActiveImageUpdate(auto on_result, failure_callback on_failure)

Calls the method EndActiveImageUpdate in the remote device.

Parameters:#

  • auto on_result: A callable (e.g. a lambda) with 0 arguments.
  • failure_callback on_failure: A callback which is called on error.

BeginPassiveComponentUpdate#

void BeginPassiveComponentUpdate(OcaComponent component, OcaNetworkAddress serverAddress, OcaString updateFileName, auto on_result, failure_callback on_failure)

Calls the method BeginPassiveComponentUpdate in the remote device. If no result and error callback is specified, the method will be called without requesting a response.

Parameters:#

  • OcaComponent component
  • OcaNetworkAddress serverAddress
  • OcaString updateFileName
  • auto on_result: A callable (e.g. a lambda) with 0 arguments.
  • failure_callback on_failure: A callback which is called on error.

EndUpdateProcess#

void EndUpdateProcess(auto on_result, failure_callback on_failure)

Calls the method EndUpdateProcess in the remote device.

Parameters:#

  • auto on_result: A callable (e.g. a lambda) with 0 arguments.
  • failure_callback on_failure: A callback which is called on error.

observeComponentVersions#

subscription observeComponentVersions(auto callback, failure_callback on_failure)

Fetches the remote property ComponentVersions and subscribes for modifications. The callback is called with the initial values of ComponentVersions and whenever it changes.

Parameters:#

  • auto callback: A callable (e.g. a lambda) with one argument: OcaList<OcaVersion> ComponentVersions
  • failure_callback on_failure: A callback which is called on error.

OnComponentVersionsChanged#

subscription OnComponentVersionsChanged(auto callback, failure_callback on_failure)

Parameters#

  • auto callback: A callable (e.g. a lambda) with one argument: OcaList<OcaVersion> ComponentVersions
  • failure_callback on_failure: A callback which is called on error.