Device Config OKIDL

Important: Amazon Confidential. This is pre-release technical documentation for an upcoming product that
has not been released to the public.

This user guide demonstrates usage of the DeviceConfig APIs.

DeviceConfig is an Omnikit interface which provides APIs for querying and modifying device
configurations in addition to sending notifications on configuration updates. DeviceConfig acts as
a central data store for system-wide configurations and provides APIs for querying and modifying
configurations. These APIs are part of the IDL file
device_config_2024_01.idl and are implemented by
/com.amazon.kepler.experinental.device_config_2024_01

This guide demonstrates API usage.

Access Control

DeviceConfig's APIs are access-controlled. Device configuration privileges are derived from device
configurations themselves; this section will explain DeviceConfig read and write privileges and
demonstrate usage in an application manifest.

Read Privileges

In order to retrieve a device configuration value for com.amazon.devconf/system/{group}/{key},

the
following privilege must be defined and used:

com.amazon.devconf.privilege.{group}.{key}

This privilege allows for retrieving a device configuration at key granularity. The privilege

com.amazon.devconf.privilege.{group}

may also be used to retrieve all keys in the group {group}.

For example, to retrieve the device configuration value in

com.amazon.devconf/system/configuration/locale the privilege
com.amazon.devconf.privilege.configuration.locale or
com.amazon.devconf.privilege.configuration
may be used.

AMAZON CONFIDENTIAL DO NOT DISTRIBUTE

Write Privileges

When modifying a device configuration, the privilege corresponding to

com.amazon.devconf/system/{group}/{key} can be:

com.amazon.devconf.privilege.{group}.{key}.write

For example, the privilege corresponding to the device configuration

com.amazon.devconf/system/configuration/locale will be
com.amazon.devconf.privilege.configuration.locale.write.

DeviceConfig allows privileges to operate at key granularity (as shown above) as well as at group
granularity. In order to modify a device configuration within a specific group {group}, the
corresponding privilege can be:

com.amazon.devconf.privilege.{group}.write

For example, to modify any device configuration {key} in

com.amazon.devconf/system/configuration/{key}, the privilege
com.amazon.devconf.privilege.configuration.write can be used to modify all device
configurations
within the group configuration.

Application Manifest

In order to add a privilege to an application, it must be placed in the application's

manifest.toml file. For example, to read from and write to the device configuration
com.amazon.devconf/system/configuration/locale, the following updates to an application's
manifest file must be made. This section will illustrate a v1 application manifest with
DeviceConfig read and write privileges.

Manifest v1

schema-version = 1

[package]
id = "com.amazon.device-config.sample"
version = "1.0.0"
title = "DeviceConfig Sample Application Package"

[components]
[[components.interactive]]
id = "com.amazon.device-config.main"
library-name = "device_config_app"
categories = ["com.amazon.category.main"]

[needs]
[[needs.privilege]]
id = "com.amazon.devconf.privilege.configuration.locale"

AMAZON CONFIDENTIAL DO NOT DISTRIBUTE

[[needs.privilege]]
id = "com.amazon.devconf.privilege.configuration.locale.write"

For each privilege needed by the application, it will have an accompanying [[needs.privilege]]
subsection in its [needs] section.

Retrieving Device Configuration Values

DeviceConfig provides two APIs for retrieving device configuration values: get() to retrieve a
single device configuration value, and getArray() for retrieving a list of device configuration
values.

This section demonstrates querying device configuration values with both APIs:
using apmf::iface::com::amazon::kepler::experimental::device_config_2024_01::
DeviceConfigNotFoundException;
using apmf::iface::com::amazon::kepler::experimental::device_config_2024_01::IDeviceConfig;

const apmf::String g_configLocale{"com.amazon.devconf/system/configuration/locale"};

const apmf::String g_configTimeZone{"com.amazon.devconf/system/configuration/time-zone"};

static apmf::Ptr<IDeviceConfig> getIDeviceConfig() {

static constexpr std::string_view s_component{"/com.amazon.kepler.experimental.device_config_2024_01"};
apmf::Ptr<apmf::IProcess> proc = apmf::GetProcessObject();

return proc->getComponent(s_component).TryQueryInterface<IDeviceConfig>();
}

void getConfigValue() {
apmf::Ptr<IDeviceConfig> component = getIDeviceConfig();
if (component == nullptr) {
/* IDeviceConfig component not found */
return;
}

try {
apmf::String value = component->get(g_configLocale);
} catch (const apmf::IoError& e) {
/* Error communicating with DeviceConfigService server */
} catch (const apmf::InvalidArgumentError& e) {
/* Invalid device configuration input */
} catch (const apmf::SecurityError& e) {
/* No permissions */
} catch (const DeviceConfigNotFoundException& e) {
/* Non-fatal exception, device configuration queried has no value */
} catch (const apmf::BaseError& e) {
/* Catch all */
}
}

void getConfigValues() {
apmf::Ptr<IDeviceConfig> component = getIDeviceConfig();
if (component == nullptr) {
/* IDeviceConfig component not found */
return;
}

try {
apmf::Array<apmf::String> configs{g_configLocale, g_configTimeZone};
apmf::Array<apmf::String> values = component->getArray(configs);
} catch (const apmf::IoError& e) {
/* Error communicating with DeviceConfigService server */
} catch (const apmf::InvalidArgumentError& e) {
/* Invalid device configuration input */
} catch (const apmf::SecurityError& e) {
/* No permissions */
} catch (const apmf::BaseError& e) {
/* Catch all */

AMAZON CONFIDENTIAL DO NOT DISTRIBUTE

 }
}

Modifying a Device Configuration Value

DeviceConfig provides a set() API which takes in a device configuration and a value. This API will
modify the device configuration to be the value and persist it across device reboots.

NOTE: Device configuration values are limited to 1,024 characters (1KB) to provide fast
data retrieval and modification.
NOTE: Device configuration values are not encrypted.
NOTE: If an empty string is provided as a device configuration value, the device configuration
will be removed from DeviceConfig. Subsequent get() calls to this device configuration will throw
a DeviceConfigNotFoundException until a non-empty value is set.

This section demonstrates modifying a device configuration value:

const apmf::String g_configTimeZone{"com.amazon.devconf/system/configuration/time-zone"};

void setConfigValue() {
apmf::Ptr<IDeviceConfig> component = getIDeviceConfig();
if (component == nullptr) {
/* IDeviceConfig component not found */
return;
}

try {
apmf::String value{"America/Los_Angeles"};

component->set(g_configTimeZone, value);
} catch (const apmf::IoError& e) {
/* Error communicating with DeviceConfigService server */
} catch (const apmf::OutOfBoundsError& e) {
/* Value set exceeds maximum device configuration value size */
} catch (const apmf::InvalidArgumentError& e) {
/* Invalid device configuration input */
} catch (const apmf::SecurityError& e) {
/* No permissions */
} catch (const apmf::NotSupportedError& e) {
/* Attempting to set a read-only device configuration */
} catch (const apmf::BaseError& e) {
/* Catch all */
}
}

Update Notification

DeviceConfig uses Kepler Messaging to send notifications on device configuration value updates.
Whenever a device configuration value has been updated, DeviceConfig will send a message using the
URI:

broadcast://*/com.amazon.devconf/system/{group}/{key}

AMAZON CONFIDENTIAL DO NOT DISTRIBUTE

For example, if the device configuration com.amazon.devconf/system/configuration/locale
has been
updated, DeviceConfig will send a Message with the URI
broadcast://*/com.amazon.devconf/system/configuration/locale via Kepler
Messaging.

The Message sent will include an attachment DeviceConfigChangeAttachment which will contain the
new value the device configuration has been set to. This may be retrieved by the attachment's
updatedValue() API.

This section demonstrates usage of the Kepler Messaging APIs to setup a notification callback
whenever a device configuration has been changed.
using apmf::iface::com::amazon::kepler::experimental::device_config_2024_01::DeviceConfigChangeAttachment;
using apmf::iface::com::amazon::kepler::experimental::device_config_2024_01::IDeviceConfig;

using apmf::iface::com::amazon::kepler::experimental_mr33::messaging::IKeplerMessagingModule;
using apmf::iface::com::amazon::kepler::experimental_mr33::messaging::IMessage;
using apmf::iface::com::amazon::kepler::experimental_mr33::messaging::IMessageChannel;
using apmf::iface::com::amazon::kepler::experimental_mr33::messaging::IMessageFilter;
using apmf::iface::com::amazon::kepler::experimental_mr33::messaging::IMessageListener;

const std::string g_channelName{};

const std::string g_topic{"broadcast://*/com.amazon.devconf/system/configuration/time-zone"};

apmf::Ptr<IMessageChannel> g_channel = nullptr;

struct SimpleListener : apmf::ApmfBase<SimpleListener, IMessageListener> {

void onMessage(apmf::View<IMessage> message) {
std::cout << "Received message for: " << message->targetUri() << std::endl;

auto attachment = message->attachment().TryQueryInterface<DeviceConfigChangeAttachment>();

if (attachment == nullptr) {
/* DeviceConfigChangeAttachment data object not found */
return;
}

std::cout << "New device configuration value: " << attachment->updatedValue() << std::endl;
}

void onError(apmf::View<IError> error) {

if (error->getTypes() == apmf::detail::ErrorTraits<apmf::IoError>::kAllTypeNames) {
/*
* Channel can no longer send/receive messages, reset the channel and implement
* retry strategy if resiliency is required
*/
...
}
}
};

void listen() {
apmf::Ptr<apmf::IProcess> proc = apmf::GetProcessObject();
auto component = proc->getComponent("/com.amazon.kepler.experimental_mr33.messaging")
.TryQueryInterface<IKeplerMessagingModule>();
if (component == nullptr) {
/* IKeplerMessagingModule not found */
return;
}

auto listener = apmf::Ptr<SimpleListener>::Make();

g_channel = component->makeMessageChannel(g_channelName, listener);

apmf::Array<Ptr<IMessageFilter>> filterArray{};
filterArray.push_back(component->makeMessageFilterBuilder()->baseUri(g_topic)->build());

g_channel->registerMessageFilter(filterArray);
}

AMAZON CONFIDENTIAL DO NOT DISTRIBUTE

AMAZON CONFIDENTIAL DO NOT DISTRIBUTE