MRM DeviceInfoDelegate Class

The DeviceInfoDelegate class provides access to device specific information, such as IP address, device volume, and connectivity state.

DeviceInfoDelegate Class Declaration

This is a sample declaration of the DeviceInfoDelegate class:

class DeviceInfoDelegate {
public:
    virtual ~DeviceInfoDelegate() {};

    virtual const char *getIPAddress() = 0;
    virtual const char *getBSSID() = 0;
    virtual const char *getESSID() = 0;
    virtual float getRSSI() = 0;
    virtual int getDeviceMainVolume() = 0;
    virtual int getDeviceIdleTime() = 0;
    virtual const char *getDeviceId() = 0;
    virtual const char *getAmazonId() = 0;
    virtual bool isDebugBuild() = 0;
    virtual bool getRegistrationState() = 0;
    virtual bool waitForAccurateSystemClock() = 0;

The functions of DeviceInfoDelegate are called:

  • During MRM SDK initialization to get necessary attributes.
  • When the MRM SDK was alerted of changes in system attribute by post functions such as WHA:postNetworkConnectionChanged().

    The MRM SDK has a work queue for all the post functions for asynchronous handling without block the caller. Basically, for example, when it is time to process the network connection change, the MRM SDK uses related functions in the DeviceInfo interface to query the latest IP address, BSSID, etc.

  • When one device wants to know some information from other devices for the management of cluster attributes.

    For example, when the master device is told to have an idle state change via postDeviceIdleChanged(), it reaches out to all the slaves to query their latest idle time via MRM SDK for the inter-device communication. Each slave then uses the getDeviceIdleTime() callback to acquire the latest idle time and report the time to the master device.

  • Any time that the MRM SDK wants to refresh cached values.

    For example, it is desired to have a diagnostic feature to support debugging cluster formation problems automatically. In this case, MRM SDK uses functions of this class to query the latest network-related information like IP address, BSSID, ESSID, etc. to help users understand why some of the devices cannot be put into the same cluster and what to do to make it work, and so on.

The WHA class requires access a device's network related attributes, such as IP address, BSSID, ESSID, and RSSI. These attributes are necessary for device-to-device communication, cluster formation, and network diagnosis within the WHA class.

Specification for these attributes:

  • IP Address: This should be in IPv4 format (e.g. 192.168.1.4). When the IP Address is unspecified or unavailable, getIPAddress() should return an empty string.
  • BSSID: This should be the raw value with six groups of two lower case hexadecimal digits separated by colons (e.g. 28:c6:8e:0b:09:fa). When it is unspecified or unavailable, getBSSID() should return an empty string.
  • ESSID: This should be the raw ESSID (e.g. Guest). When this is unspecified or unavailable, getESSID()should return nullptr. The actual value for ESSID should be an arbitrary sequence of 0 to 32 octets.
  • RSSI: This should be in the format of dBm. The value should be -99 if RSSI is unavailable.

getIPAddress()

Implement this function to return the IP address (IPv4) of the device. Return nullptr if it is unspecified or unavailable.

virtual const char *getIPAddress() = 0;

getBSSID()

Implement this function to return the BSSID. It should be the raw value with six groups of two hexadecimal digits in lower case separated by colons. For example, 28:c6:8e:0b:09:fa. Return nullptr if it is unspecified or unavailable.

virtual const char *getBSSID() = 0;

getESSID()

Implement this function to return the ESSID to which the device is currently associated. It should be the raw value without being obfuscated. Return nullptr if it is unspecified or unavailable.

virtual const char *getESSID() = 0;

getRSSI()

Implement this function to return the current RSSI value.

virtual float getRSSI() = 0;

getDeviceMainVolume()

Implement this function to return the latest device main volume (general playback volume, not including alarm volume, etc.) as a percentage (0 to 100) rounded to an integer.

virtual int getDeviceMainVolume() = 0;

getDeviceIdleTime()

Implement this function to return the latest idle time, which is the time in seconds since any action that confirms a user is in the presence of the product, such as a user interacting with on-product buttons, speaking with Alexa, or using a GUI affordance.

When postDeviceIdleTimeChanged() is called, the MRM SDK uses getDeviceIdleTime() to get the latest idle time on each local device, calculates a cluster idle time and sends the cluster idle time to Alexa. The MRM SDK does not call this at boot-up time.

virtual int getDeviceIdleTime() = 0;

getDeviceId()

Implement this function to return the identifier of the local device for cluster management. It should be unique and static like DSN. Since this value will be shared with other devices or related services, you should obfuscate it for privacy, as needed.

virtual const char *getDeviceId() = 0;

getAmazonId()

Implement this function to return the unique identifier assigned by Amazon to this type of device.

virtual const char *getAmazonId() = 0;

waitForAccurateSystemClock()

This function should block for up to two minutes waiting for clock synchronization. When the clock is set from network time, this function should return true; if this function times out the function should return false.

virtual bool waitForAccurateSystemClock() = 0;

isDebugBuild()

Implement this function to return true if the device is under debug build. If the function returns false (for a release build), the MRM SDK enables an internal logging filter to obfuscate privacy information such as IP address.

virtual bool isDebugBuild() = 0;

getRegistrationState()

Implement this function to return true when there is a registration activity for the device. This function is called when WHA::postRegistrationChanged() is called.

A registration activity is when a user sets up an Alexa account via the Amazon Alexa App or your companion app.

virtual bool getRegistrationState() = 0;